Fix API call descriptions in ARCH

1 files changed, 26 insertions, 21 deletions

diff --git a/ARCH b/ARCH
index d6199bf..23d32d1 100644
--- a/ARCH
+++ b/ARCH
@@ -253,24 +253,28 @@ Requests for admins:
 * `GET /1.0/lorry/<lorryspecid>` causes WEBAPP to return a JSON map
   (dict) with all the information about the specified Lorry
   specification. (RQ/SPEC)
-* `POST /1.0/move-to-top/<lorryspecid>` where `lorryspecid` is the id
-  of a Lorry specification in the run queue, causes WEBAPP to move the
-  specified spec to the head of the run queue, and store this in
-  STATEDB. It doesn't affect currently running jobs. (RT/TOP)
-* `POST /1.0/move-to-bottom/<lorryspecid>` is like `/move-to-top`, but
-  moves the job to the end of the run queue. (RT/BOT)
+* `POST /1.0/move-to-top` with `path=lorryspecid` as the body, where
+  `lorryspecid` is the id (path) of a Lorry specification in the run
+  queue, causes WEBAPP to move the specified spec to the head of the
+  run queue, and store this in STATEDB. It doesn't affect currently
+  running jobs. (RT/TOP)
+* `POST /1.0/move-to-bottom` with `path=lorryspecid` in the body is
+  like `/move-to-top`, but moves the job to the end of the run queue.
+  (RT/BOT)
 
 * `GET /1.0/list-running-jobs` causes WEBAPP to return a JSON list of
   ids of all currently running jobs. (RQ/RUNNING)
 * `GET /1.0/job/<jobid>` causes WEBAPP to return a JSON map (dict)
   with all the information about the specified job.
-* `POST /1.0/stop-job/<jobid>` where `jobid` is an id of a running job,
-  causes WEBAPP to record in STATEDB that the job is to be killed, and
-  waits for it to be killed. (Killing to be done when MINION gets
-  around to it.) This request returns as soon as the STATEDB change is
-  done.
+* `POST /1.0/stop-job` with `job_id=jobid` where `jobid` is an id of a
+  running job, causes WEBAPP to record in STATEDB that the job is to
+  be killed, and waits for it to be killed. (Killing to be done when
+  MINION gets around to it.) This request returns as soon as the
+  STATEDB change is done.
 * `GET /1.0/list-all-jobs` causes WEBAPP to return a JSON list of ids
   of all jobs, running or finished, that it knows about. (RQ/ALLJOBS)
+* `POST /1.0/remove-job` with `job_id=jobid` in the body, removes a
+  stopped job from the state database.
 
 Requests for MINION:
 
@@ -282,16 +286,17 @@ Requests for MINION:
   WEBAPP updates STATEDB to record that the job is allocated to a
   MINION.
 * `POST /1.0/job-update` is used by MINION to push updates about the
-  job it is running to WEBAPP. The body is a JSON object containing
-  additional information about the job, such as data from its
-  stdout/stderr, and current resource usage. There MUST be at least
-  one `job-update` call, which indicates the job has terminated.
-  WEBAPP responds with a status indicating whether the job should
-  continue to run or be terminated (RR/TIMEOUT). WEBAPP records the
-  job as terminated only after MINION tells it the job has been
-  terminated. MINION makes the `job-update` request frequently, even
-  if the job has produced no output, so that WEBAPP can update a
-  timestamp in STATEDB to indicate the job is still alive.
+  job it is running to WEBAPP. The body sets fields `exit` (exit code
+  of program, or `no` if not set), `stdout` (some output from the
+  job's standard output) and `stderr` (ditto, but standard error
+  output). There MUST be at least one `job-update` call, which
+  indicates the job has terminated. WEBAPP responds with a status
+  indicating whether the job should continue to run or be terminated
+  (RR/TIMEOUT). WEBAPP records the job as terminated only after MINION
+  tells it the job has been terminated. MINION makes the `job-update`
+  request frequently, even if the job has produced no output, so that
+  WEBAPP can update a timestamp in STATEDB to indicate the job is
+  still alive.
 
 Other requests: