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
- Get the capabilities for a print configuration
- Create a print job
- Get the status for a print job
- Download the report for a print job
- Cancel a print job
- List available fonts
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.
Response Sample
Request URI: GET /simple/capabilities.json
{
"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 sent by email and the feature is enabled in the app, a 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). Otherwisefalse
. -
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 iswaiting
. error
: An error message, if an error occurred.-
downloadURL
: The URL under which the report will be available once the print job has finished.
Response 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.
{
"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
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