Introduction
Root URI
https://api.priintcloud.com/auth # service to retrieve auth tokens
https://api.priintcloud.com/rest # all other services requiring auth tokens
Versioning of the REST API
There is only one version of the REST API currently.
We always try to be backward compatible.
If - in the future - backward compatibility cannot be guaranteed anymore, we may introduce new versions of the API through a different root URI like https://api.priintcoud.com/rest-v2.
Authorization
Access to the rendering REST API requires a valid JWT (JSON web token) which is sent in the "Authorization" header of each request. This is an example:
Authorization: Bearer eyJmb28iOiJiYXIifQ==
Bearer tokens are acquired from the /auth/{tenant}/tokens endpoint in the typical style of OAuth2 password authentication.
See Authorization Service for details.
Supported Content Types
The rendering service will convert XML data into PDF documents, enriching them with images of a different type on the way. So, a bunch of data formats take part in the main processing pipeline.
Apart from that, the request bodies of the REST API are either url-form-encoded or JSON. Response bodies are in JSON format.
Unless explicitly mentioned, requests MUST use "accept" header with JSON type.
Accept: application/json
For request having a data payload, the "content-type" header MUST be JSON unless explicitly stated otherwise.
Content-Type: application/json
The XML format for rendering requests is such an exception.
Here is a summary of media types used in requests and responses.
Request body types
| Media Type | Description |
|---|---|
| application/json | used in 'POST /renderpdf', requires a transform configuration (i.e. a XSLT file) |
| application/xml | default input for 'POST /renderpdf' |
| application/zip | alternative input for 'POST /renderpdf' |
| application/x-www-form-urlencoded | OAuth2 request form to retrieve bearer tokens |
Response body types
| Media Type | Description |
|---|---|
| application/json | default output format for the API |
| application/zip | packaged artifact and log files for a job |
| application/pdf | rendered PDF |
Response Codes
Here comes a list of HTTP response codes for successful operation or client side error with application-specific interpretation.
5xx codes may also occur with their standard meanings.
| Code | Name | Description |
|---|---|---|
| 200 | OK | Operation was successful. |
| 201 | Created | Object was created. |
| 202 | Accepted | Job was scheduled for execution. Returning the ticketId for the job in the response body. |
| 400 | Bad Request | Request parameter or body missing or not value not valid for the parameter. Inspect the JSON response for more details. |
| 401 | Unauthorized | Bearer token missing or invalid. Check Authorization header or token value. |
| 402 | Payment Required | Quota exceeded for renderings. Check subscription. |
| 403 | Forbidden | Token is not entitled to use the resource. Check the token, especially the scope. |
| 404 | Not Nound | Check the request URL. Are the values for tenant, project, ticket, etc. correct? Check ticket completion state. |
| 405 | Method Not Allowed | Only HTTP GET and POST are in allowed for the basic rendering services. |
| 406 | Not Acceptable | Accept header either missing or value is not supported. |
| 408 | Request Timeout | On synchronous rendering requests the PDF could not be created in acceptable time. |
| 415 | Unsupported Media Type | Accept header is not supported by te service. See above list of media types. |
| 429 | Too Many Requests | Rate limiting. Currently not in use. |
Response Bodies on Errors
Depending on the specific error, you may get more or less diagnostic information.
E.g. Sending inappropriate content-type data will lead to 406 errors like this:
HTTP/1.1 406 Not Acceptable
{
"status": 406,
"message": "Requested media type not supported"
}
E.g. an Internal Server Error can not be totally excluded and could come up like this.
HTTP/1.1 500 Internal Server Error
Content-Type: application/json
{
"timestamp": "2023-05-01T14:21:05.402Z",
"status": 500,
"error": "Input could not be enqueued. No fanout data found.",
"path": "/rest/tenants/example.com/projects/datasheets/renderpdf"
}
Service Availability
priint:cloud does not limit the rate of inputs per client sent to the system via API calls.
Sending many PDF rendering requests in a short time will have the following effects
- the service will add the input data into a job queue and only start to process them into PDFs if there are free resources to do so
- the priority of jobs will be downgraded when the rate per client (actually per "project") is increasing
Our platform is designed to scale-up processing resources on request bursts, and later to scale down after processing. Scaling operations have some latency 8say about 30 sec to some minutes). Keep that in mind.
OpenAPI
Our rendering API is described via OpenAPI. There is a Swagger UI available to visualize the OpenAPI doc.