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

On 18-01-2016 19:05, Aline Manera wrote: > 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. git am complained about an extra white space at the EOL ↑.

> + > +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) >