Search manual:

- Main page
- Introduction
- Hello, world!
- Basics
  - How to write the layout
  - Structure of the data file and the layout rules
  - Outputting objects
  - Grid
  - Areas on the page (PositioningArea)
  - File organization
  - Hyphenation / language settings
  - Using fonts
  - Text formats
  - Text formatting
  - Colors
- Programming
- Image inclusion
- Tables
- Advanced topics
  - Bookmarks
  - Creation of XML structures
  - Print output / crop marks
  - Using CSS with the speedata Publisher
  - Groups (virtual objects)
  - Virtual pages
  - Rotation of contents
  - Sorting data
  - Wrap around images
  - Page types
  - Starting the Publisher via the Hotfolder
  - Lua-Filter / pre-processing
  - Schema validation
  - Quality assurance and PDF comparison
  - Troubleshooting / Debugging
  - Server mode (REST API)
  - Control of the layout when calling the Publisher
  - Create and use images with MetaPost
- Cookbook
  - Thumb index
  - Embed multipage PDF files
  - Layout optimization using groups
  - Imitate bulleted lists
  - Automatically generated directories
  - Create table of contents in one go
  - Page numbers: Page x of y
- Installation instructions
- File name in the Publisher
- speedata Publisher defaults
- Running the speedata publisher on the command line
- How to configure the speedata publisher
- Lenghts and units
- XPath- and Layoutfunctions
- Internal variables
- Associate XML editor with schema
  - Visual Studio Code
  - OxygenXML
  - Atom
- Changelog
- Glossary
- Compatibility with other software
- Command reference
  - A
  - Action
  - AddSearchpath
  - AtPageCreation
  - AtPageShipout
  - AttachFile
  - Attribute
  - B
  - Barcode
  - Bold
  - BoldItalic
  - Bookmark
  - Box
  - Br
  - Case
  - Circle
  - ClearPage
  - Color
  - Column
  - Columns
  - Compatibility
  - Contents
  - Copy-of
  - DefineColor
  - DefineColorprofile
  - DefineFontalias
  - DefineFontfamily
  - DefineGraphic
  - DefineMatter
  - DefineTextformat
  - Element
  - Fallback
  - Fontface
  - ForAll
  - Frame
  - Grid
  - Group
  - Groupcontents
  - HSpace
  - Hyphenation
  - I
  - Image
  - Include
  - Initial
  - InsertPages
  - Italic
  - Layout
  - Li
  - LoadDataset
  - LoadFontfile
  - Loop
  - Makeindex
  - Margin
  - Mark
  - Message
  - NewPage
  - NextFrame
  - NextRow
  - NoBreak
  - Ol
  - Options
  - Otherwise
  - Output
  - Overlay
  - Pageformat
  - Pagetype
  - Paragraph
  - PDFOptions
  - PlaceObject
  - Position
  - PositioningArea
  - PositioningFrame
  - ProcessNode
  - Record
  - Regular
  - Rule
  - SaveDataset
  - SavePages
  - SetGrid
  - SetVariable
  - SortSequence
  - Stylesheet
  - Span
  - Sub
  - Sup
  - Switch
  - Table
  - TableNewPage
  - Tablefoot
  - Tablehead
  - Tablerule
  - Td
  - Text
  - Textblock
  - Tr
  - Trace
  - Transformation
  - U
  - Ul
  - Until
  - URL
  - Value
  - VSpace
  - While

Version 4.8.0
Search manual

- Main page
- Introduction
- Hello, world!
- Basics
  - How to write the layout
  - Structure of the data file and the layout rules
  - Outputting objects
  - Grid
  - Areas on the page (PositioningArea)
  - File organization
  - Hyphenation / language settings
  - Using fonts
  - Text formats
  - Text formatting
  - Colors
- Programming
- Image inclusion
- Tables
- Advanced topics
  - Bookmarks
  - Creation of XML structures
  - Print output / crop marks
  - Using CSS with the speedata Publisher
  - Groups (virtual objects)
  - Virtual pages
  - Rotation of contents
  - Sorting data
  - Wrap around images
  - Page types
  - Starting the Publisher via the Hotfolder
  - Lua-Filter / pre-processing
  - Schema validation
  - Quality assurance and PDF comparison
  - Troubleshooting / Debugging
  - Server mode (REST API)
  - Control of the layout when calling the Publisher
  - Create and use images with MetaPost
- Cookbook
  - Thumb index
  - Embed multipage PDF files
  - Layout optimization using groups
  - Imitate bulleted lists
  - Automatically generated directories
  - Create table of contents in one go
  - Page numbers: Page x of y
- Installation instructions
- File name in the Publisher
- speedata Publisher defaults
- Running the speedata publisher on the command line
- How to configure the speedata publisher
- Lenghts and units
- XPath- and Layoutfunctions
- Internal variables
- Associate XML editor with schema
  - Visual Studio Code
  - OxygenXML
  - Atom
- Changelog
- Glossary
- Compatibility with other software
- Command reference
  - A
  - Action
  - AddSearchpath
  - AtPageCreation
  - AtPageShipout
  - AttachFile
  - Attribute
  - B
  - Barcode
  - Bold
  - BoldItalic
  - Bookmark
  - Box
  - Br
  - Case
  - Circle
  - ClearPage
  - Color
  - Column
  - Columns
  - Compatibility
  - Contents
  - Copy-of
  - DefineColor
  - DefineColorprofile
  - DefineFontalias
  - DefineFontfamily
  - DefineGraphic
  - DefineMatter
  - DefineTextformat
  - Element
  - Fallback
  - Fontface
  - ForAll
  - Frame
  - Grid
  - Group
  - Groupcontents
  - HSpace
  - Hyphenation
  - I
  - Image
  - Include
  - Initial
  - InsertPages
  - Italic
  - Layout
  - Li
  - LoadDataset
  - LoadFontfile
  - Loop
  - Makeindex
  - Margin
  - Mark
  - Message
  - NewPage
  - NextFrame
  - NextRow
  - NoBreak
  - Ol
  - Options
  - Otherwise
  - Output
  - Overlay
  - Pageformat
  - Pagetype
  - Paragraph
  - PDFOptions
  - PlaceObject
  - Position
  - PositioningArea
  - PositioningFrame
  - ProcessNode
  - Record
  - Regular
  - Rule
  - SaveDataset
  - SavePages
  - SetGrid
  - SetVariable
  - SortSequence
  - Stylesheet
  - Span
  - Sub
  - Sup
  - Switch
  - Table
  - TableNewPage
  - Tablefoot
  - Tablehead
  - Tablerule
  - Td
  - Text
  - Textblock
  - Tr
  - Trace
  - Transformation
  - U
  - Ul
  - Until
  - URL
  - Value
  - VSpace
  - While

- Dieses Handbuch auf Deutsch

# Server mode (REST API)

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

| Server mode is intended for a non-public environment. There are no authentication methods and no mechanisms to protect documents.

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`.

Method | URL | Short description
--- | --- | ---
GET | `/available` | Return 200 to check if the server is running.
POST | `/v0/publish` | Send data to the server to start a publishing run.
GET | `/v0/publish/<id>` | Check if a publishing run is finished.
GET | `/v0/pdf/<id>` | Wait for the completion of a PDF.
POST | `/v0/pdf` | Send data and wait for the completion of a PDF.
GET | `/v0/data/<id>` | Load the `data.xml` from the publishing run.
GET | `/v0/layout/<id>` | Load the `layout.xml` from the publishing run
GET | `/v0/statusfile/<id>` | Load the status file (`publisher.status`) from the publishing run.
GET | `/v0/status` | Overview of the current publishing processes.
GET | `/v0/status/<id>` | Overview of a publishing process.
GET | `/v0/delete/<id>` | Delete a publishing run.

## `/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