[Kimchi-devel] [PATCH] [Wok 4/6] Split API documentation into multiple files
Aline Manera
alinefm at linux.vnet.ibm.com
Tue Jan 19 11:38:18 UTC 2016
On 01/19/2016 12:07 AM, Jose Ricardo Ziviani wrote:
>
>
> 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 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.
>
> git am complained about an extra white space at the EOL ↑.
Thanks, Ziviani! I will fix it before applying.
>
>> +
>> +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)
>>
>
More information about the Kimchi-devel
mailing list