API
The API module is an HTTP/1 and HTTP/2 (H2C) server. Other modules may add routes, middlewares, and health checks.
Properties
- Port
- Timeout
- Root path
- Trace
- Health
--api-port int Set the port on which the API should listen (default 3000)
--api-port-from-env string Set the environment variable with the port on which the API should listen - override the default port
--api-timeout duration Set the time limit for requests (default 30s)
The properties --api-read-timeout
, --api-process-timeout
and --api-write-timeout
are deprecated in favor of
--api-timeout
.
--api-root-path string Set the root path of the API - for service discovery via URL paths (default "/")
--api-trace-header string Set the header name to use for identifying requests (default "Gotenberg-Trace")
--api-disable-health-check-logging bool Disable health check logging
Routes
Health
GET /health
- Success
- Error
Status: 200 OK
Content-Type: application/json
Gotenberg-Trace: {trace}
Body:
{
"status": "up",
"details": {
"moduleX": {
"status": "up",
"timestamp": "2021-07-01T08:05:14.603364Z"
},
"moduleY": {
"status": "up",
"timestamp": "2021-07-01T08:05:14.603364Z"
},
}
}
Status: 503 Service Unavailable
Content-Type: application/json
Gotenberg-Trace: {trace}
Body:
{
"status": "down",
"details": {
"moduleX": {
"status": "up",
"timestamp": "2021-07-01T08:05:14.603364Z"
},
"moduleY": {
"status": "down",
"timestamp": "2021-07-01T08:05:14.603364Z",
"error": "An health check error"
},
}
}
The details
section gathers the health checks from modules. If none, this entry is not present.
Currently, only the following module provides a health check:
Modules
multipart/form-data
METHOD /forms/{module}/{handler}
The following modules provide multipart/form-data
routes:
- Success
- Error
Status: 200 OK
Content-Disposition: attachement; filename={output-filename.ext}
Content-Type: {content-type}
Content-Length: {content-length}
Gotenberg-Trace: {trace}
Body: {output-file}
Status: {status}
Content-Type: text/plain; charset=UTF-8
Gotenberg-Trace: {trace}
Body: {error}
Other routes
METHOD /{module}/{handler}
Currently, only the following module provides a non-multipart/form-data
route:
Middlewares
Trace all routes
The trace, or request ID, identifies a request in the logs.
By default, the API generates a UUID trace for each request. However, you may also specify the trace per request,
thanks to the Gotenberg-Trace
header.
For instance:
curl \
--request POST 'http://localhost:3000/forms/chromium/convert/url' \
--header 'Gotenberg-Trace: debug' \
--form 'url="https://my.url"' \
-o my.pdf
The API adds a header Gotenberg-Trace
to each response. If you're using the webhook feature, it also adds the header
to each request to your callbacks.
You may customize the trace header thanks to the --api-trace-header
property.
Timeout all routes
The API returns a 503 Service Unavailable
response if a request fails to finish before a given duration.
You may customize the time limit thanks to the --api-timeout
property.
The API will close the socket if it fails to read the request body before the time limit. It will also close the socket if the API fails to write the response after a duration equal to two times the time limit. However, this scenario is unlikely.
Output Filename multipart
By default, the API generates a UUID filename. However, you may also specify the filename per request, thanks to
the Gotenberg-Output-Filename
header.
For instance:
curl \
--request POST 'http://localhost:3000/forms/chromium/convert/url' \
--header 'Gotenberg-Output-Filename: result' \
--form 'url="https://my.url"' \
-O -J
The API adds the file extension automatically; you don't have to set it.
Modules
Currently, only the following module provides a middleware: