From 8b05a0d495593a8d250ec36758ddef5c67515d14 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Petr=20=C5=A0abata?= <contyk@redhat.com>
Date: Tue, 21 Jun 2016 16:28:05 +0200
Subject: [PATCH] First take at the orchestrator API, unversioned
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Petr Šabata <contyk@redhat.com>
---
 README.rst | 112 ++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 110 insertions(+), 2 deletions(-)

diff --git a/README.rst b/README.rst
index 50e4f4df..4804b5b7 100644
--- a/README.rst
+++ b/README.rst
@@ -15,6 +15,114 @@ tasks:
   services can pick up the work.
 
 Client-side API
----------------
+===============
 
-TBD
+The orchestrator implements a RESTful interface for module build submission and
+state querying.
+
+Module build submission
+-----------------------
+
+Module submission is done via posting the modulemd SCM URL.
+
+::
+
+    POST /rida/module-builds/
+
+.. code:: json
+
+    {
+        "scmurl": "git://pkgs.fedoraproject.org/modules/foo.git/foo.yaml#f1d2d2f924e986ac86fdf7b36c94bcdf32beec15
+    }
+
+The response, in case of a successful submission, would include the task ID.
+
+::
+
+    HTTP 201 Created
+
+.. code:: json
+
+    {
+        id: 42
+    }
+
+Module build state query
+------------------------
+
+Once created, the client can query the current build state by requesting the
+build task's URL.  Querying the BPO service might be preferred, however.
+
+::
+
+    GET /rida/module-builds/42
+
+The response, if the tasks exists, would include various pieces of information
+about the build task.
+
+::
+
+    HTTP 200 OK
+
+.. code:: json
+
+    {
+        "id": 42,
+        "state": "building",
+        "tasks": {
+            "rpms/foo-1.23" : "6378/closed",
+            "rpms/bar-5.0" : "6379/open"
+        }
+    }
+
+"id" is the ID of the task.  "state" refers to the module build state and might
+be one of "init", "building", "done", "failed" or "locked".  "tasks" is a
+dictionary of component names in the format of "type/NVR" and related koji
+tasks and their states.
+
+Listing all module builds
+-------------------------
+
+The list of all tracked builds and their states can be obtained by querying the
+"module-builds" resource.
+
+::
+
+    GET /rida/module-builds/
+
+::
+
+    HTTP 200 OK
+
+.. code:: json
+
+    [
+        {
+            "id": 41",
+            "state": "done"
+        },
+        {
+            "id": 42,
+            "state": "building"
+        },
+        {
+            "id": 43,
+            "state": "init"
+        }
+    ]
+
+
+HTTP Response Codes
+-------------------
+
+Possible response codes are for various requests include:
+
+- HTTP 200 OK - The task exists and the query was successful.
+- HTTP 201 Created - The module build task was successfully created.
+- HTTP 400 Bad Request - The client's input isn't a valid request.
+- HTTP 403 Forbidden - The SCM URL is not pointing to a whitelisted SCM server.
+- HTTP 404 Not Found - The requested URL has no handler associated with it.
+- HTTP 500 Internal Server Error - An unknown error occured.
+- HTTP 501 Not Implemented - The requested URL is valid but the handler isn't
+  implemented yet.
+- HTTP 503 Service Unavailable - The service is down, possibly for maintanance.