Edit this page on Github

Web Service API

This document outlines the web service API for the DAISY Pipeline.

Resources

RESTful web services describe a system in terms of its resources. Generally speaking, resources can be created, retrieved, modified, and deleted.

The main resources in this web service are scripts, jobs, clients and data-types.

A script is a Pipeline XProc script. The script is identified with a unique URI. It is described in terms of its functionality and all of its inputs and options.

A job is the execution of a script. Jobs have unique IDs and are created using input and option values. Jobs produce downloadable results.

A client is an application using the Pipeline via its API. Examples of clients are web applications and command line utilities. A client is not a human user.

A data type determines the possible values a script option can take. It is defined in an XML syntax (a subset of RelaxNG).

Accessing Resources

RESTful applications communicate via HTTP and use standard methods and status codes to create, get, and delete resources.

The following HTTP methods are used here:

Every method is not implemented for every resource because in some cases, the method wouldn’t be relevant. Any unimplemented methods will respond with HTTP 405 “Method Not Allowed”.

The API

WS Status

Scripts

Get all scripts

Get a single script

Jobs

Create a job

Read more about creating jobs.

Get all jobs

Get a single job

Delete a single job

Get the result for a job

Get the log file for a job

Data types

Get all data types

Get a single data type

Admin

In addition to managing scripts and jobs, the web service also provides an administrative interface. Use of this API is restricted to use by authorized clients; i.e. those with ADMIN permissions.

Stop the web service

Get all clients

Create a new client

Get a single client

Delete a client

Modify a client

Schema

Schema for all the XML formats used in this API can be found here.

Authentication

When authentication is enabled, the Pipeline only accepts requests from authorized clients. In order to become authorized, a client must be added to the database of clients using the admin API described in [#Admin].

The client must add the following query parameters to each request:

Note that it is possible to start the web service with authentication disabled. This is appropriate when the web service is running only locally or in other similarly controlled environments. In this case, none of the authentication parameters are required, and any that are sent are ignored.

Read more about authentication.

Local File System mode

The web service is by default run in what is referred to as local FS mode. The property org.daisy.pipeline.ws.localfs must be set to change it. In local mode, the web service assumes read/write access to the disk. Documents that would normally be sent as part of a zip archive or inline request can be referred to by their local file path instead. Output options are enabled and output is written to disk instead of being zipped up for download.

See a sample document.

Web Service internal errors

In the unlikely but not impossible case that the Pipeline WS suffered from an internal error, a descriptive xml is returned along with the HTTP 500 header.

See the xml sample document.