Server-mode

When the speedata Publisher is started in the server-mode (sp server), it expects HTTP-requests on port 5266 (configurable).

The server mode must be used in a restricted environment. The current API (v0) exposes all PDF files and other private information to all users with access to the server. Future versions of the API might handle authentication.

/available

Return HTTP-status 200 (OK).

/v0/publish

When called with a POST-request, the speedata Publisher expects a JSON file in the follwing format:

{<filename>:<base64 encoded file contents>,
 <filename>:<base64 encoded file contents>,
 ...
 }

for example:

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

These files are copied into an empty directory and after the request, the program sp is called without arguments. The result of the POST request is in the form:

{"id":"752869708"}

with an HTTP status code 201 (Created).

If the JSON file is defective, the HTTP status code is 400 (bad request) and the returned contents is a text string, such as

illegal base64 data at input byte 0

Parameters

A parameter can be specified to set the result name of the PDF (without extension):

/v0/publish?jobname=myfile sets the jobname to "myfile", so /v0/pdf/<id> returns the data with the given filename (plus the .pdf) extension. This is done via the HTTP header Content-Disposition. If the parameter is not supplied, the jobname is taken from the file publisher.cfg. If the file is not supplied or if the parameter is not set in that file, the jobname is set to publisher.

You can also submit additional variables: /v0/publish?vars=var1%3Dvalue1. This is similar to the command line parameter --var. The parameter is URL-encoded in the form var1=value1,var2=value2,var3=value3....

/v0/delete/<id>

GET: Remove the directory for this ID. Returns 200 if the ID is valid, 404 if not.

/v0/publish/<id>

A GET request with an id from the aforementioned POST request returns a JSON file with the following contents:

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

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

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

If the PDF file is not finished yet:

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

The directory of the publishing run will be deleted right after the request, unless the URL has the suffix ?delete=false.

/v0/pdf/<id>

A GET request with an id from the aforementioned POST request. In case of success, the PDF file gets returned with a 200 OK status. The request waits for the PDF file to be ready. On error, the answer is an error code:

Status code Description
200 OK PDF rendered OK
404 Not Found Id is invalid
406 Not Acceptable PDF has errors

/v0/data/<id>

Return the data file that has been copied to the server before. The format can be set with the URL parameter format:

Format Description
json or JSON Return a JSON-file such as {"contents":"<XML Text>"}
base64 The result is an XML file, that is encoded base64 (PGRhdGE+CiAgICA8....hPgo=)
(no format) Returns the XML file (<data>...</data>)

Example: http://127.0.0.1:5266/v0/layout/1347678770?format=base64

/v0/layout/<id>

Return the layout file that has been copied to the server before. The format can be set with the URL parameter format:

Format Description
json or JSON Return a JSON-file such as {"contents":"<XML Text>"}
base64 The result is an XML file, that is encoded base64 (PGRhdGE+CiAgICA8....hPgo=)
(no format) Returns the XML file (<Layout>...</Layout>)

Example: http://127.0.0.1:5266/v0/layout/1347678770?format=base64

/v0/statusfile/<id>

Return the file publisher.status that has been created during the last run. The format can be set with the URL parameter format:

Format Description
json or JSON Return a JSON-file such as {"contents":"<XML Text>"}
base64 The result is an XML file, that is encoded base64 (PGRhdGE+CiAgICA8....hPgo=)
(no format) Returns the XML file (<Status>...</Status>)

Example: http://127.0.0.1:5266/v0/statusfile/1347678770?format=base64

/v0/status

Return the status for all publishing runs, that were started with /v0/publish.

The returned JSON file has the following format:

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

See /v0/status/<id> for the meaning of the fields.

/v0/status/<id>

Determines the current status of the publishing run, which was POSTed to /v0/publish.

The returned JSON has the following keys:

Key Description
errorstatus Is the request valid? Possible answers are error and ok. If it is error, the value of the message contains the reason for the error, the value for the key result is without any meaning.
result Contains failed if the PDF file is created but with errors. not finished if the PDF file is not finished, ok if everything went fine.
message Contains an informal message, for example no errors found or 2 errors occurred during publishing run.
finished Time stamp when the PDF was finished written to. Format is RFC3339, for example 2015-12-25T12:03:04+01:00.

/v0/format

Generates hyphenation points for a text, that is given via POST-request. The text is encoded in XML and can contain mandatory line breaks (<br class="keep" />) or mandatory mid-word breaks (<shy class="keep" />).

The returned XML has the same format as the request.

The XML-structure of the request and answer must confirm to the following RelaxNG Compact schema:

namespace a = "http://relaxng.org/ns/compatibility/annotations/1.0"
start =
  element root {
    element text {
      (attribute hyphenate-limit-before { xsd:unsignedInt },
       attribute hyphenate-limit-after { xsd:unsignedInt })?,
      mixed {
        element br {
          attribute class { "keep" | "soft" }?,
          empty
        }+,
        element shy {
          attribute class { "keep" | "soft" }?,
          empty
        }+
      }
    }+
  }
Version: 3.5.9 | Start page | Element reference | Other language: German