REST API v1 - kuhnuri/kuhnuri-queue GitHub Wiki

This describes the resources that make up the Kuhnuri Queue REST API v1.

Schema

All API access is over HTTP or HTTPS. All data is sent and received as JSON.

All timestamps return in ISO 8601 format:

YYYY-MM-DDTHH:MM:SSZ

Authentication

The REST API uses a token based authentication. All requests must contain a HTTP header X-Auth-Token that contains a valid authorization token. The only exception to this is the registration end-point.

Parameters

Many API methods take optional parameters. For GET requests, any parameters not specified as a segment in the path can be passed as an HTTP query string parameter:

curl -i "https://example.com/api/v1/jobs?state=done"

For POST, PATCH, PUT, and DELETE requests, parameters not included in the URL should be in the body of the request, encoded as JSON with a Content-Type of application/json:

Registration

Login and register as a worker

POST /api/v1/login

Parameters

name	type	description
id	string	Worker ID
password	string	Worker password that matches the ID
uri	string	Worker callback URI that can be used to communicate with a worker

Example

{
  "id": "worker",
  "password": "0925d96f-9f1d-4fbf-888f-16f5616a921b",
  "uri": "https://example.com/worker/"
}

Response

Response when authentication is successful:

200 Ok
X-Auth-Token: 6a9d2f90-e90d-4030-bd20-ed3ca5cf52fc

An authentication token is returned in the header. This authentication token must be added to all subsequent requests to the REST API.

Response when authentication fails:

401 Unauthorized

Unregister

Unregister as an available worker

POST /api/v1/logout

Response

Response when unregistration is successful

200 Ok

Jobs

Listing jobs

List all jobs in the queue:

GET /api/v1/jobs

Response

200 Ok

[
  {
    "id": "cd010166-7b69-4c9a-a3d2-697a7b6ac280",
    "input": "jar:s3://example/b34a487a-b031-4bf0-893d-18bed8c4959b/src.zip!/start.ditamap",
    "output": "s3://example/b34a487a-b031-4bf0-893d-18bed8c4959b/res.zip",
    "transtype": [
      {
        "id": "0c8ca310-0e1f-4ed5-9fbd-7c977d33af03",
        "job": "cd010166-7b69-4c9a-a3d2-697a7b6ac280",
        "input": "jar:s3://example/b34a487a-b031-4bf0-893d-18bed8c4959b/src.zip!/start.ditamap",
        "output": "s3://example/b34a487a-b031-4bf0-893d-18bed8c4959b/res.zip",
        "transtype": "pdf2",
        "params": {},
        "status": "process",
        "processing": "2018-03-23T09:58:38.628Z",
        "worker": "worker"
      }
    ],
    "params": {},
    "status": "process",
    "priority": 0,
    "created": "2018-03-23T08:58:35.208Z"
  }
]

Get a single job

GET /api/v1/job/:id

Response

200 Ok

{
  "id": "cd010166-7b69-4c9a-a3d2-697a7b6ac280",
  "input": "jar:s3://example/b34a487a-b031-4bf0-893d-18bed8c4959b/src.zip!/start.ditamap",
  "output": "s3://example/b34a487a-b031-4bf0-893d-18bed8c4959b/res.zip",
  "transtype": [
    {
      "id": "0c8ca310-0e1f-4ed5-9fbd-7c977d33af03",
      "job": "cd010166-7b69-4c9a-a3d2-697a7b6ac280",
      "input": "jar:s3://example/b34a487a-b031-4bf0-893d-18bed8c4959b/src.zip!/start.ditamap",
      "output": "s3://example/b34a487a-b031-4bf0-893d-18bed8c4959b/res.zip",
      "transtype": "pdf2",
      "params": {},
      "status": "process",
      "processing": "2018-03-23T09:58:38.628Z",
      "worker": "worker"
    }
  ],
  "params": {},
  "status": "process",
  "priority": 0,
  "created": "2018-03-23T08:58:35.208Z"
}

Creating jobs

Create a new job:

POST /api/v1/job

Parameters

name	type	description
input	string	Input resource URI
output	string	Resource URI where results should be stored
transtype	string[]	Transtypes of the conversion that should be ran
params	object	Key-value pairs of parameters to be passed to conversion
filter	string	URI of the filter that should be used

Example

{
  "input": "jar:jar:s3://example/b34a487a-b031-4bf0-893d-18bed8c4959b/src.zip!/start.ditamap",
  "output": "s3://example/b34a487a-b031-4bf0-893d-18bed8c4959b/res.zip",
  "transtype": ["pdf2"],
  "params": {},
  "filter": null
}

Response

201 Created

{
  "id": "cd010166-7b69-4c9a-a3d2-697a7b6ac280",
  "input": "jar:s3://example/b34a487a-b031-4bf0-893d-18bed8c4959b/src.zip!/start.ditamap",
  "output": "s3://example/b34a487a-b031-4bf0-893d-18bed8c4959b/res.zip",
  "transtype": [
    {
      "id": "0c8ca310-0e1f-4ed5-9fbd-7c977d33af03",
      "job": "cd010166-7b69-4c9a-a3d2-697a7b6ac280",
      "transtype": "pdf2",
      "params": {},
      "status": "queue"
    }
  ],
  "params": {},
  "status": "queue",
  "priority": 0,
  "created": "2018-03-23T08:58:35.208Z"
}

Download job log

GET /api/v1/job/:id/log

TODO

Workers

Request work

Request a job that is available for processing and matches the worker's transtype capabilities:

POST /api/v1/work

Response

Response when no matching job is available:

204 No Content

Response when matching job is available:

200 Ok

{
  "id": "0c8ca310-0e1f-4ed5-9fbd-7c977d33af03",
  "job": "cd010166-7b69-4c9a-a3d2-697a7b6ac280",
  "input": "jar:s3://example/b34a487a-b031-4bf0-893d-18bed8c4959b/src.zip!/start.ditamap",
  "output": "s3://example/b34a487a-b031-4bf0-893d-18bed8c4959b/res.zip",
  "transtype": "pdf2",
  "params": {},
  "status": "process",
  "processing": "2018-03-23T09:58:38.628Z",
  "worker": "worker"
}

Submit job results

When submitting job results, the status field should be set to either done or error depending on conversion results.

PUT /api/v1/work

{
  "task": {
    "id": "0c8ca310-0e1f-4ed5-9fbd-7c977d33af03",
    "job": "cd010166-7b69-4c9a-a3d2-697a7b6ac280",
    "input": "jar:s3://example/b34a487a-b031-4bf0-893d-18bed8c4959b/src.zip!/start.ditamap",
    "output": "s3://example/b34a487a-b031-4bf0-893d-18bed8c4959b/res.zip",
    "transtype": "pdf2",
    "params": {},
    "status": "process",
    "processing": "2018-03-23T09:58:38.628Z",
    "worker": "worker"
  },
  "log": []
}

Response

200 Ok

Client errors

Sending invalid JSON or paremeters will result in a 400 Bad Request response.

Sending invalid fields will result in a 422 Unprocessable Entity response.

422 Unprocessable Entity

{
  "code": "ERR003",
  "message": "Invalid JSON"
}