Change: update API description (such as it is)

1 files changed, 12 insertions, 47 deletions

diff --git a/architecture.mdwn b/architecture.mdwn
index 1fdf122..769450c 100644
--- a/architecture.mdwn
+++ b/architecture.mdwn
@@ -598,53 +598,18 @@ server to run a pipeline.
 Ick controller resources and API
 -----------------------------------------------------------------------------
 
-A project consists of a list of pipelines and parameters for them:
-
-    {
-        "project": "liw.fi",
-        "parameters": {
-            "rsync_target": "www-data@www.example.com/srv/http/liw.fi"
-        },
-        "pipelines" [
-            ""
-        ]
-    }
-
-A pipeline resoure:
-
-    {
-        "name": "ikiwiki-config",
-        "actions": [
-            { "shell": "cat src/ikiwiki.setup.template > ikiwiki.setup" },
-            { "shell": "echo \"destdir: {{ workspace }}/html\" >> ikiwiki.setup" },
-            { "name": "mkdir", "dirname": "html" }
-        ]
-    }
-
-Here:
-
-- 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 actions
-- each pipeline should declare what parameters it expects, but nothing
-  checks that
-
-A pipeline status resource at
-`/projects/PROJECTNAME/pipelines/PIPELINENAME`, created automatically
-when a project resource is updated to include the pipeline:
-
-    {
-        "status": "idle/triggered/running/paused"
-    }
-
-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
-idle.
-
-A build resource is created automatically, at
-`/builds/PROJECTNAME/BUILDNUMBER`, a pipeline is triggered. It can't
-be changed via the API.
+See the example project for examples. Each item in the `projects` and
+`pipelines` lists is a resource. The example is in YAML syntax, but is
+trivially converted to JSON, which the API talks. (The exampel is
+input to the `icktool` command and is meant to be human-editable. YAML
+is better for that, than JSON.)
+
+For a fuller description of the APIs, see the [yarn][] scenario tests
+in the ick source code: <http://git.liw.fi/ick2/tree/yarns>
+
+A build resource is created automatically, when a project is triggerd,
+at `/builds/BUILDID`, a pipeline is triggered. It can't be changed via
+the API.
 
     {
         "project": "liw.fi",