dj-journal's API: digging for music for a DJ, by the operations their agent calls.

Every request but GET / carries the header x-api-key, whose value is the DJ's API key: a fixed string, unique to each DJ.

The header Accept names the form of the answer: text/plain for text, application/json for JSON.

Each operation of the dj-journal command line is at a path of its own, its words joined by slashes: dj-journal wish list is /wish/list. One that only reads is a GET, its fields in the query string; one that writes is a POST, its fields in a JSON body sent with Content-Type: application/json. A field is named as the command's argument or option, in lower case, without its dashes and with _ between its words. An answer that is not a 2xx is a refusal: its JSON says "ok": false, and its "error" names its code, what it refuses and how to mend it.

A read, dj-journal wish list --stage dropped, with $KEY the DJ's API key and $URL this server's address:

  curl -H "x-api-key: $KEY" -H "Accept: application/json" \
    "$URL/wish/list?stage=dropped"

  200 OK
  {"op": "wish.list", "ok": true, "data": {"stage": "dropped", ..., "wishes": []}, ...}

A long operation, such as a dig, is run as a job: its POST answers 202 at once, with the job's Location to ask until it ends. dj-journal dig label-releases Dekmantel:

  curl -i -X POST -H "x-api-key: $KEY" -H "Accept: application/json" \
    -H "Content-Type: application/json" -d '{"label": "Dekmantel"}' \
    "$URL/dig/label-releases"

  202 Accepted
  Location: /job/show?id=job/019a4b5c-1d2e-7f30-8a41-5b6c7d8e9f00

  curl -H "x-api-key: $KEY" -H "Accept: application/json" \
    "$URL/job/show?id=job/019a4b5c-1d2e-7f30-8a41-5b6c7d8e9f00"

  200 OK
  {"op": "job.show", "ok": true, "data": {"state": "waiting", ...}, ...}

The job's GET answers 200 however the job goes, and its "state" says how: ask again, a few seconds apart, while it is waiting, running or interrupted. It ends done, with "ending" done or partial; failed, with "error" its code, message and fix; or dropped. A job says how its operation went, not what it found: once it is done, the GETs read that. The same call POSTed again before its job ends answers that job's Location.

support: tarea-fina@jm.guide42.com
version: 0.6.0