Change: add icktool as component, describe API RESTfulness

1 files changed, 35 insertions, 8 deletions

diff --git a/architecture.mdwn b/architecture.mdwn
index e648237..c7640a3 100644
--- a/architecture.mdwn
+++ b/architecture.mdwn
@@ -148,15 +148,16 @@ Ick components
 Ick consists of several independent services. This document describes
 how they are used individually and together.
 
-* The **controller** keeps track of projects, pipelines, workers, and
-  the current state of each. It decides which build action is next,
-  and who should execute it. The controller provides a simple,
-  unconditional "build this project" API call, which the user can use.
+* The **controller** keeps track of projects, pipelines, workers,
+  builds, and the current state of each. It decides which build action
+  is next, and who should execute it. The controller provides a
+  simple, unconditional "build this project" API call, which the user
+  can use.
 
 * A **worker-manager** represents and directly controls a **build
   host**. It queries the controller for work, and executes the related
-  action on the build host, and then reports results back to the
-  controller. Results include any output (stdout, stderr) and exit
+  action on its build host, and then reports results back to the
+  controller. Results consist of any output (stdout, stderr) and exit
   code.
 
 * An **artifact store** stores individual files (which may be tar
@@ -169,9 +170,15 @@ how they are used individually and together.
   authenticates itself to the IDP, and receives an access token. The
   client includes the access token with each call to an API, the API
   provider validates the token, and inspects it to see what the client
-  is allowed to do. (FIXME: this is not yet implemented)
+  is allowed to do.
 
-On an implementation level, the various services of Ick may be
+* The **icktool** command line tool provides the ick user interface.
+  It get an access token from the identity provider, and uses the
+  controller and artifact store APIs to manage project and pipeline
+  descriptions, build artfifacts, trigger builds, and view build
+  status.
+
+On an implementation level, the various services of ick may be
 implemented using any language and framework that works. However, to
 keep things simple. initially we'll be using Python 3, Bottle, and
 Green Unicorn. Also, the actual API implementation ("backend") will be
@@ -211,6 +218,26 @@ Individual APIs
 This chapter covers interactions with individual APIs.
 
 
+RESTful APIs
+-----------------------------------------------------------------------------
+
+All APIs provided by ick are of the "RESTful" style. Data is modelled
+as "resources", and managed using the operations shown below. The
+examples assume a type of resource called `foo`. Resources are in JSON
+format, except for build artifacts, which are blobs.
+
+* create a resource: `POST /foos` – the response has the id of
+  the new response
+* retrieve a resource: `GET /foos/ID`
+* list all resources of type `foo`: `GET /foos`
+* update a resoruce: `PUT /foos/ID` – the updated resource is in
+  the request body
+* remove a resource: `DELETE /foos/ID`
+
+Note that individual fields of a resource can't be retrieved or
+updated. From the API's point of view, a resource is atomic.
+
+
 On security
 -----------------------------------------------------------------------------