[Kimchi-devel] [PATCH] [Wok 4/6] Split API documentation into multiple files
Jose Ricardo Ziviani
joserz at linux.vnet.ibm.com
Tue Jan 19 02:07:41 UTC 2016
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 ↑.
> +
> +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)
>
--
Jose Ricardo Ziviani
-----------------------------
Software Engineer
Linux Technology Center - IBM
More information about the Kimchi-devel
mailing list