• Main page
• Advanced topics
• Server mode (REST API)

Server mode (REST API)PRO

The Publisher provides an interface that can be used to pass requests for document generation via HTTP. The server mode is started with

sp server

on the command line. The server mode offers the option

• transfer data to the server and start a run
• Determine status of the run (is the process still running?)
• download finished PDF files
• Other status files to read

The server establishes the connection on the IP address 127.0.0.1 and port 5266. The address can be changed with the parameters address and port in the configuration file or on the command line, see the appendix about configuration.

Example of a configuration file:

[server]
port = 9999
address = 0.0.0.0
extra-dir = /var/projects/fonts:/var/projects/images
filter = convertdata.lua

An overview of all API methods follows. The current version number of the API is 0, so all methods are addressed via http://127.0.0.1:5266/v0/... If there will be incompatible changes in the future, these can be reached in the version number /v1/…​, the existing methods will still be accessible via /v0.

/available

Without version number. Returns the HTTP status 200.

/v0/publish

If the URL is called with a POST request, the speedata Publisher expects a JSON file in the following format

{<filename>:<base64 coded content>,
 <filename>:<base64 coded content>,
 ...
 }

such as

{"layout.xml": "PD94bWwgdmVyc2lv..."
 "data.xml": "PGRhdGE+CiAgICA8Y29udGVudHM+PCFbQ0RBVEFbPHV..." }

These files are copied to an empty directory on the server and sp is called there. The return is in the form

{"id": "752869708"}

with an HTTP status code 201 (Created).

If the JSON file is incorrect, an HTTP status code 400 (Bad Request) is returned with the textual content of the error message, for example

illegal base64 data at input byte 0

Parameter

The following URL parameters can be specified in the POST request:

jobname

Sets the name of the output, which is specified when the PDF file is downloaded (HTTP header Content-Disposition). Alternatively it is taken from the file publisher.cfg or the default publisher.

vars

Sets variables for the Publisher run. Specification in the form var1=value1,var2=value2,var3=value3…​, but URL-coded.

mode

Set the mode for the run. Specification in the form mode1,mode2,mode3…​, but URL-encoded.

Example

The request to

http://127.0.0.1:5266/v0/publish?vars=myvar%3D12345&mode=a4paper%2Cprint

sets myvar to 1234 and enables the modes a4paper and print.

/v0/publish/<id>

A GET request to this URL with an id from the POST request described above returns a JSON file with the content:

{"status": "ok",
 "path":"/path/to/publisher.pdf",
 "blob": "<base64 encoded PDF>",
 "finished": "2015-03-03T13:12:55+01:00",
 "output": "<unencoded output from the sp command>"
 }

or, in case of error, if the id is unknown:

{"status": "error", "path":"", "blob": "id unknown"}

If the PDF file has not yet been written:

{"status": "error", "path":"", "blob": "in progress"}

If any other error occurs:

{"status": "error", "path":"", "output": "some helpful output"}

The directory containing the PDF file will be deleted after this request, unless the URL contains the delete parameter with the value false.

There can be more fields in the JSON file in future versions.

/v0/pdf

A POST request to send data to the server and receive a PDF. See the data layout in the description of /v0/publish and the return codes in the section /v0/pdf/<id>.

/v0/pdf/<id>

A GET request with the id from the POST request of /v0/publish. If successful, the PDF file with status code 200 and the file name publisher.pdf is returned. The request is waiting for the publishing process to be completed. In case of an error only an error code is returned (return value and description):

200 OK

PDF was generated without errors

404 Not Found

id invalid

406 Not Acceptable

PDF was generated incorrectly

The directory containing the PDF file will be deleted after this request, unless the URL contains the delete parameter with the value false.

/v0/data/<id>

Returns the data file that was previously copied to the server. The format can be specified using the URL parameter format, for example http://127.0.0.1:5266/v0/data/1347678770?format=base64:

json or JSON

Returns a JSON file in the format {"contents":"<XML Text>"}

base64

Results in an XML file that is base64 encoded (PGRhdGE+CiAgICA8…​hPgo=)

(not specified)

Writes an XML file (<data>…​</data>)

/v0/layout/<id>

Returns the layout XML that was previously copied to the server. The format can be specified using the URL parameter format. Example as above.

json or JSON

Returns a JSON file in the format {"contents":"<XML Text>"}

base64

Results in an XML file that is base64 encoded (PGRhdGE+CiAgICA8…​hPgo=)

(not specified)

Writes an XML file (<Layout>…​</Layout>)

/v0/statusfile/<id>

Returns the publisher.status file created by the run. The format can be specified using the URL parameter format, (example as in /v0/data/<id>).

json or JSON

Returns a JSON file in the format {"contents":"<XML Text>"}.

base64

Results in an XML file that is base64 encoded (PGRhdGE+CiAgICA8…​hPgo=)

(not specified)

Writes an XML file (<Status>…​</Status>)

/v0/status

Returns the status of all publishing runs started with /v0/publish.

The returned JSON file has the following format

{
  "1997009134": {
    "error status": "ok",
    "result": "finished",
    "message": "no errors found",
    "finished": "2016-05-23T11:14:14+02:00"
  },
  "1997329145": {
    "error status": "ok",
    "result": "finished",
    "message": "no errors found",
    "finished": "2016-05-23T11:14:14+02:00"
  }
}

The individual fields have the same meaning as described under /v0/status/<id>.

/v0/status/<id>

Determines the status of the publisher run that was sent to /v0/publish via POST request.

The returned JSON file has the following keys:

errorstatus

Is the request valid? Possible answers are error and ok. If error, then the message key contains the reason for the error, the result field is irrelevant in this case. If ok, then the field result contains the value not finished if the PDF file has not yet been created.

result

After the PDF file has been created, the result field contains the value failed if errors occurred during PDF creation, not finished if the publishing process is still going on, otherwise ok.

message

Contains an informal message about the result. For example, no errors found or 2 errors occurred during publishing run.

finished

Contains the timestamp when the PDF was finished. Format corresponds to RFC3339, for example 2015-12-25T12:03:04+01:00.

/v0/delete/<id>

GET: Deletes the directory with this id. Returns 200 if the id exists, 404 if not.

• Troubleshooting / Debugging
• Control of the layout when calling the Publisher