Web Protocol

The API is the web/HTTP protocol allowing a client to interact with the print service via the web.

List available print configurations

Lists the identifiers of all print configurations that are available in the MapFish Print instance.

URI

GET /apps.json

Response Sample

[
"simple",
"default"
]

Get the capabilities for a print configuration

Return the capabilities for a specific print configuration.

URI

GET /:appId/capabilities.json

:appId should be the identifier of one of the available print configurations.

Request Sample

Request URI: GET /simple/capabilities.json

Response Sample

{
    "app": "simple",
    "layouts": [
        {
            "name": "A4 Portrait",
            "attributes": [
                ...
            ]
        }
    ],
    "formats": [
        "bmp",
        "gif",
        "pdf",
        "png",
        "tif",
        "tiff"
    ],
    "smtp": {
      "enabled": false
    }
}

The smtp section shows "enabled": true if the reports can be sent by email. To enable this feature, please refer to the !smtpConfig section.

Create a print job

Send a print request to create a print job.

URI

POST /:appId/report.:format

:appId should be the identifier of one of the available print configurations.

:format should be one of the formats supported by the specified print configuration (e.g. pdf or png).

Request

The POST body must be either a print request encoded as JSON, or a form-encoded request where the field spec contains the print request encoded as JSON.

The print request must contain the following properties:

  • layout: One of the available layouts of the specified print configuration.
  • attributes: A list of attributes that are required by the specified layout.

If the report must be sent by email and the feature is enabled in the app, an smtp property looking like that (subject and body are optional) must be added to the request: 

{
  "smtp": {
    "to": "toto@example.com",
    "subject": "The email subject",
    "body": "Some <b>html</b> body"
  }
}

Response

The JSON response contains the following properties:

  • ref: A reference id that can be used to request the status for the print job or to download the finished report.
  • statusURL: The URL to request the status.
  • downloadURL: The URL under which the report will be available once the print job has finished.

Request Sample

Request URI: POST /simple/report.pdf

Request body

{
    "layout": "A4 Portrait",
    "attributes": {
        "map": {
            "center": [
                957352.8034848921,
                5936844.140278816
            ],
            "dpi": 72,
            "layers": [
              ...
            ],
            "projection": "EPSG:3857",
            "rotation": 0,
            "scale": 25000
        },
        "scalebar": {
            "projection": "EPSG:21781"
        },
        "title": "Sample Print"
    }
}

Response Sample

{
    "ref": "15179fee-618d-4356-8114-cfd8f146e273@3067ade6-0768-4fc6-b41d-40422d0cdb8b",
    "statusURL": "/print/status/15179fee-618d-4356-8114-cfd8f146e273.json",
    "downloadURL": "/print/report/15179fee-618d-4356-8114-cfd8f146e273"
}

Get the status for a print job

Returns the status for a print job.

You should not call this API if you requested the report to be sent by email.

URI

GET /status/:referenceId.json

:referenceId should be the reference id of a print job, which is returned when creating a job.

Response

The JSON response contains the following properties:

  • done: true if the print job has finished (either successful or not). Otherwise false.
  • status: One of the following values:
    • waiting: The job hasn't yet started processing and is waiting in a queue.
    • running: The job is currently being processed.
    • finished: The job has finished processing.
    • canceled: The job was canceled.
    • error: There was an error executing the job.
  • elapsedTime: The elapsed time in ms from the point the job started. If the job is done, this is the duration it took to process the job.
  • waitingTime: A rough estimate for the time in ms the job still has to wait in the queue until it starts processing. Only set when the status is waiting.
  • error: An error message, if an error occurred.
  • downloadURL: The URL under which the report will be available once the print job has finished.

Request Sample

Request URI: GET /status/15179fee-618d-4356-8114-cfd8f146e273.json

You should not call this API if you requested the report to be sent by email.

Response Sample

{
    "done": false,
    "status": "running",
    "elapsedTime": 507,
    "waitingTime": 0,
    "downloadURL": "/print/report/15179fee-618d-4356-8114-cfd8f146e273"
}

Download the report for a print job

Downloads a finished print job.

URI

GET /report/:referenceId

:referenceId should be the reference id of a print job, which is returned when creating a job.

Response

Returns the report in the format that was requested when created the print job.

Request Sample

Request URI: GET /report/15179fee-618d-4356-8114-cfd8f146e273

Cancel a print job

Request the cancellation of a print job.

URI

DELETE /cancel/:referenceId

:referenceId should be the reference id of a print job, which is returned when creating a job.

Response

Status: 200 OK

Request Sample

Request URI: DELETE /cancel/15179fee-618d-4356-8114-cfd8f146e273

Create a print job and download its report

Triggers the creation of a print job, then download the report. Although it seems synchronous from the client perspective, the print job might be run by a different server in cluster mode. Despite this, it is not the recommended manner to use the print server (as too many requests in parallel will grab all the server resources).

URI

POST /:appId/buildreport.:format

:appId should be the identifier of one of the available print configurations.

:format should be one of the formats supported by the specified print configuration (e.g. pdf or png).

Response

Status: 200 OK

Request Sample

Request URI: POST /simple/buildreport.pdf

See Create a print job request sample for the request body.

List Available Fonts

List fonts installed in Java Runtime on server. This lists the fonts that can be put in the Jasper Report Templates

URI

GET /fonts

Response

A JSON array containing all the available fonts face names on the server that can be used in Jasper Report Templates

Request Sample

Request URI: GET /fonts