Change: update API descriptions

1 files changed, 35 insertions, 35 deletions

diff --git a/architecture.mdwn b/architecture.mdwn
index efb5152..2261bb2 100644
--- a/architecture.mdwn
+++ b/architecture.mdwn
@@ -440,13 +440,13 @@ a set of "resources". These data objects that can be addressed using
 URLs and they are manipulated using HTTP methods: GET, POST, PUT,
 DELETE. There can be many instances of a type of resource. These are
 handled as a collection. Example: given a resource type for projects
-Ick should build, the API would have the following calls:
+ick should build, the API would have the following calls:
 
-    POST /projects -- create a new project, giving it an ID
-    GET /projects -- get list of all project ids
-    GET /projects/ID -- get info on project ID
-    PUT /projects/ID -- update project ID
-    DELETE /projects/ID -- remove a project
+* `POST /projects` – create a new project, giving it an ID
+* `GET /projects` – get list of all project ids
+* `GET /projects/ID` – get info on project ID
+* `PUT /projects/ID` – update project ID
+* `DELETE /projects/ID` – remove a project
 
 [RESTful]: https://en.wikipedia.org/wiki/Representational_state_transfer
 
@@ -454,10 +454,14 @@ Resources are all handled the same way, regardless of the type of the
 resource. This gives a consistency that makes it easier to use the
 APIs.
 
+Except for blobs, all resources are in the JSON format. Blobs are just
+sequences of bytes and don't have structure. Build artifacts and build
+logs are blobs.
+
 Note that the server doesn't store any client-side state at all. There
 are no sessions, no logins, etc. Authentication is handled by
-attaching (in the `Authorization` header) a token to each request. An
-Identity Provider gives out the tokens to API clients, on request.
+attaching (in the `Authorization` header) a token to each request. The
+identity provider gives out the tokens to API clients, on request.
 
 Note also the API doesn't have RPC style calls. The server end may
 decide to do some action as a side effect of a resource being created
@@ -471,13 +475,7 @@ server to run a pipeline.
 Ick controller resources and API
 -----------------------------------------------------------------------------
 
-A project consists of a workspace specification, and an ordered list
-of pipelines. Additionally the project has a list of builds, and for
-each build a build log, and metadata (time and duration of build, what
-triggered it, whether it was successful or not). Also, a current state
-of the workspace.
-
-A project resource:
+A project consists of a list of pipelines and parameters for them:
 
     {
         "project": "liw.fi",
@@ -498,14 +496,16 @@ A pipeline resoure:
             { "shell": "echo \"destdir: {{ workspace }}/html\" >> ikiwiki.setup" },
             { "name": "mkdir", "dirname": "html" }
         ]
-    },
+    }
 
 Here:
 
-- the pipeline consists of a sequence of steps
-- each step is a shell snippet, a Python3 snippet, or a built-in
+- the pipeline consists of a sequence of actions
+- each action is a shell snippet, a Python3 snippet, or a built-in
   operation implemented by the worker-manager directly
-- project parameters may be used by pipeline steps
+- project parameters may be used by pipeline actions
+- each pipeline should declare what parameters it expects, but nothing
+  checks that
 
 A pipeline status resource at
 `/projects/PROJECTNAME/pipelines/PIPELINENAME`, created automatically
@@ -516,28 +516,26 @@ when a project resource is updated to include the pipeline:
     }
 
 To trigger a pipeline, PUT a pipeline resource with a status field of
-"triggered". It is an error to do that when current status is not
+`triggered`. It is an error to do that when current status is not
 idle.
 
 A build resource is created automatically, at
-/projects/PROJECTNAME/builds, when a pipeline actually starts (not
-when it's triggered). It can't be changed via the API.
+`/builds/PROJECTNAME/BUILDNUMBER`, a pipeline is triggered. It can't
+be changed via the API.
 
     {
-        "build": "12765",
         "project": "liw.fi",
+        "build_id": "liw.fi/12765",
+        "build_number": 12765,
+        "log": "logs/liw.fi/12765",
+        "parameters": {},
         "pipeline": "ikiwiki-run",
         "worker": "bartholomew",
-        "status": "running/success/failure",
-        "started": "TIMESTAMP",
-        "ended": "TIMESTAMP",
-        "triggerer": "WHO/WHAT",
-        "trigger": "WHY"
+        "status": "building",
     }
 
-A build log is stored at `/projects/liw.fi/builds/12765/log` as a
-blob. The build log is appended to by the worker-manager by reporting
-output.
+A build log is stored at `/logs/liw.fi/12765` as a blob. The build log
+is appended to by the worker-manager by reporting output.
 
 Workers are registered to the controller by creating a worker
 resource. Later on, we can add useful metadata to the resource, but
@@ -562,11 +560,12 @@ A work resource resource tells a worker what to do next:
 
 The controller provides a simple API to give work to each worker:
 
-    GET /work/bartholomew
-    PUT /work/bartholomew
+    GET /work
+
+The controller identifies the worker from the access token.
 
-The controller keeps track of which worker is currently running which
-pipeline
+The controller keeps track of which worker is currently running each
+pipeline.
 
 Work output resource:
 
@@ -582,3 +581,4 @@ Work output resource:
 
 When `exit_code` is non-null, the step has finished, and the
 controller knows it should schedule the next step in the pipeline.
+If `exit_code` is a non-zero integer, the action failed.