Chapter 11. Using the Docserv² API
Prev

Chapter 11. Using the Docserv² API

Table of Contents

Docserv² includes a nascent (read, "not particularly good") REST API.

The API runs at the API interface defined via the site configuration’s host and port attributes. For more information, see the section called “The [server] section”.

The dscmd command-line API client

The official API client is dscmd which is available as an RPM package from the openSUSE Build Service’s Documentation:Tools repository or from the dscmd GitHub repository. Installation from the RPM works analogously to that of Docserv² itself, see the section called “Installing Docserv²”.

The dscmd client includes a --help switch.

To set up dscmd, create a configuration file ~/.dscmd-server.conf with the following content:

server=[HOST]
port=[PORT]
validtargets=[TARGETS]

Replace [HOST], [PORT], and [TARGETS] with values appropriate for your installation. Target names must match the names defined using the name attribute of the target sections in the site configuration (the section called “Target sections”). You can combine multiple target values using commas characters (,), for example: validtargets=target_1,target_2. (Do not add spaces around the comma characters.)

This configuration file will be sourced by Bash. This means it must follow Bash syntax (and may contain arbitrary code).

API calls

Checking build status

To check the current build statuses and review the past build queue, make a GET request to the JSON endpoint http://[HOST]:[PORT]/.

Alternatively, use dscmd queue.

Sending a build instruction

To send a build instruction, make a POST request to the endpoint http://[HOST]:[PORT]/ with JSON data attached:

> curl \
    --header "Content-Type: application/json" \
    --request POST \
    --data '{"target":"[TARGET]","product":"[PRODUCT]","docset":"[DOCSET]","lang":"[LANGUAGE_CODE]"}' \
    [HOST]:[PORT]

Replace [TARGET], [PRODUCT], [DOCSET], [LANGUAGE_CODE], [HOST], and [PORT] with appropriate values. You can combine multiple build instructions into a single POST requests by sending a data field with multiple JSON objects separated with comma characters (,).

Alternatively, use:

> dscmd trigger \
    --target=[TARGET]
    --product=[PRODUCT_ID] --docset=[DOCSET_ID]
    --lang=[LANGUAGE_CODE].

Within each parameter, you can combine multiple values using comma characters (,), for example: --target=target_1,target_2. (Do not add spaces around the comma characters. Always use equal-to characters [=] as shown in the example.)