[Kimchi-devel] [PATCH] [Wok 4/6] Split API documentation into multiple files
Aline Manera
alinefm at linux.vnet.ibm.com
Mon Jan 18 21:05:52 UTC 2016
That way is easy to user/developer find to the API documentation without the
need to search a large file.
Also add API examples to guide user on how to use it.
Signed-off-by: Aline Manera <alinefm at linux.vnet.ibm.com>
---
configure.ac | 1 +
docs/API.md | 76 ----------------------------------------------------
docs/API/Makefile.am | 22 +++++++++++++++
docs/API/README.md | 43 +++++++++++++++++++++++++++++
docs/API/plugins.md | 13 +++++++++
docs/API/tasks.md | 45 +++++++++++++++++++++++++++++++
docs/Makefile.am | 3 ++-
7 files changed, 126 insertions(+), 77 deletions(-)
delete mode 100644 docs/API.md
create mode 100644 docs/API/Makefile.am
create mode 100644 docs/API/README.md
create mode 100644 docs/API/plugins.md
create mode 100644 docs/API/tasks.md
diff --git a/configure.ac b/configure.ac
index 915b2f8..3f302cf 100644
--- a/configure.ac
+++ b/configure.ac
@@ -90,6 +90,7 @@ AC_CONFIG_FILES([
Makefile
docs/Makefile
docs/wokd.8
+ docs/API/Makefile
src/Makefile
src/nginx/Makefile
src/wok/Makefile
diff --git a/docs/API.md b/docs/API.md
deleted file mode 100644
index 0ec1653..0000000
--- a/docs/API.md
+++ /dev/null
@@ -1,76 +0,0 @@
-## Wok REST API Specification
-
-The API provides functionality to the application and may be used directly by
-external tools. In the following sections you will find the specification of
-all Collections and Resource types that are supported and the URIs where they
-can be accessed. In order to use the API effectively, please the following
-general conventions:
-
-* The **Content Type** of the API is JSON. When making HTTP requests to this
- API you should specify the following headers:
- * Accept: application/json
- * Content-type: application/json
-* A **Collection** is a group of Resources of a given type.
- * A **GET** request retrieves a list of summarized Resource representations
- This summary *may* include all or some of the Resource properties but
- *must* include a link to the full Resource representation.
- * A **POST** request will create a new Resource in the Collection. The set
- of Resource properties *must* be specified as a JSON object in the request
- body.
- * No other HTTP methods are supported for Collections
-* A **Resource** is a representation of a singular object in the API (eg.
- Virtual Machine).
- * A **GET** request retrieves the full Resource representation.
- * A **DELETE** request will delete the Resource. This request *may* contain
- a JSON object which specifies optional parameters.
- * A **PUT** request is used to modify the properties of a Resource (eg.
- Change the name of a Virtual Machine). This kind of request *must not*
- alter the live state of the Resource. Only *actions* may alter live state.
- * A **POST** request commits an *action* upon a Resource (eg. Start a
- Virtual Machine). This request is made to a URI relative to the Resource
- URI. Available *actions* are described within the *actions* property of a
- Resource representation. The request body *must* contain a JSON object
- which specifies parameters.
-* URIs begin with '/' to indicate Wok server root.
- * Variable segments in the URI begin with a ':' and should replaced with the
- appropriate resource identifier.
-
-
-### Collection: Plugins
-
-**URI:** /plugins
-
-**Methods:**
-
-* **GET**: Retrieve a summarized list names of all UI Plugins
-
-### Collection: Tasks
-
-**URI:** /tasks
-
-**Methods:**
-
-* **GET**: Retrieve a summarized list of current Tasks
-
-### Resource: Task
-
-**URI:** /tasks/*:id*
-
-A task represents an asynchronous operation that is being performed by the
-server.
-
-**Methods:**
-
-* **GET**: Retrieve the full description of the Task
- * id: The Task ID is used to identify this Task in the API.
- * status: The current status of the Task
- * running: The task is running
- * finished: The task has finished successfully
- * failed: The task failed
- * message: Human-readable details about the Task status
- * target_uri: Resource URI related to the Task
-* **POST**: *See Task Actions*
-
-**Actions (POST):**
-
-*No actions defined*
diff --git a/docs/API/Makefile.am b/docs/API/Makefile.am
new file mode 100644
index 0000000..4f4b1cb
--- /dev/null
+++ b/docs/API/Makefile.am
@@ -0,0 +1,22 @@
+#
+# Project Wok
+#
+# Copyright IBM Corp, 2016
+#
+# This library is free software; you can redistribute it and/or
+# modify it under the terms of the GNU Lesser General Public
+# License as published by the Free Software Foundation; either
+# version 2.1 of the License, or (at your option) any later version.
+#
+# This library is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+# Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public
+# License along with this library; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
+
+apidocdir = $(datadir)/wok/doc/API
+
+dist_apidoc_DATA = $(wildcard *.md) $(NULL)
diff --git a/docs/API/README.md b/docs/API/README.md
new file mode 100644
index 0000000..57c4c00
--- /dev/null
+++ b/docs/API/README.md
@@ -0,0 +1,43 @@
+## Wok REST API Specification
+
+The API provides functionality to the application and may be used directly by
+external tools.
+
+In order to use the API effectively, please use the following general
+conventions:
+
+#### Content Type
+The **Content Type** of the API is JSON.
+When making HTTP requests to this API you should specify the following headers:
+ * Accept: application/json
+ * Content-type: application/json
+
+#### Collection
+A **Collection** is a group of Resources of a given type.
+ * A **GET** request retrieves a list of summarized Resource representations
+ This summary *may* include all or some of the Resource properties but
+ *must* include a link to the full Resource representation.
+ * A **POST** request will create a new Resource in the Collection. The set
+ of Resource properties *must* be specified as a JSON object in the request
+ body.
+ * No other HTTP methods are supported for Collections
+
+#### Resource
+A **Resource** is a representation of a singular object in the API (eg. Virtual
+Machine)
+ * A **GET** request retrieves the full Resource representation.
+ * A **DELETE** request will delete the Resource. This request *may* contain
+ a JSON object which specifies optional parameters.
+ * A **PUT** request is used to modify the properties of a Resource (eg.
+ Change the name of a Virtual Machine). This kind of request *must not*
+ alter the live state of the Resource. Only *actions* may alter live state.
+ * A **POST** request commits an *action* upon a Resource (eg. Start a
+ Virtual Machine). This request is made to a URI relative to the Resource
+ URI. Available *actions* are described within the *actions* property of a
+ Resource representation. The request body *must* contain a JSON object
+ which specifies parameters.
+
+#### URIs
+The Wok URIs starts with '/' to indicate the root server.
+Variable segments in the URI begin with a colon (':') and should replaced with
+the appropriate resource identifier.
diff --git a/docs/API/plugins.md b/docs/API/plugins.md
new file mode 100644
index 0000000..aaa37b5
--- /dev/null
+++ b/docs/API/plugins.md
@@ -0,0 +1,13 @@
+## REST API Specification for Plugins
+
+### Collection: Plugins
+
+**URI:** /plugins
+
+**Methods:**
+
+* **GET**: Retrieve a summarized list names of all UI Plugins
+
+#### Examples
+GET /plugins
+[pluginA, pluginB, pluginC]
diff --git a/docs/API/tasks.md b/docs/API/tasks.md
new file mode 100644
index 0000000..e0c404f
--- /dev/null
+++ b/docs/API/tasks.md
@@ -0,0 +1,45 @@
+## REST API Specification for Tasks
+
+### Collection: Tasks
+
+**URI:** /tasks
+
+**Methods:**
+
+* **GET**: Retrieve a summarized list of current Tasks
+
+#### Examples
+GET /tasks
+[{task-resource1}, {task-resource2}, {task-resource3}, ...]
+
+### Resource: Task
+
+**URI:** /tasks/*:id*
+
+A task represents an asynchronous operation that is being performed by the
+server.
+
+**Methods:**
+
+* **GET**: Retrieve the full description of the Task
+ * id: The Task ID is used to identify this Task in the API.
+ * status: The current status of the Task
+ * running: The task is running
+ * finished: The task has finished successfully
+ * failed: The task failed
+ * message: Human-readable details about the Task status
+ * target_uri: Resource URI related to the Task
+* **POST**: *See Task Actions*
+
+**Actions (POST):**
+
+*No actions defined*
+
+#### Examples
+GET /tasks/1
+{
+ id: 1,
+ status: running,
+ message: "Clonning guest",
+ target_uri: "/plugins/kimchi/vms/my-vm/clone"
+}
diff --git a/docs/Makefile.am b/docs/Makefile.am
index 738d42b..e98ae81 100644
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -19,10 +19,11 @@
# License along with this library; if not, write to the Free Software
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
+SUBDIRS = API
+
docdir = $(datadir)/wok/doc
dist_doc_DATA = \
- API.md \
README.md \
wokd.8 \
$(NULL)
--
2.5.0
More information about the Kimchi-devel
mailing list