Re: [Kimchi-devel] [PATCH] [Wok 4/6] Split API documentation into multiple files

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(a)linux.vnet.ibm.com&gt; --- 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)