From 2a3e7affea8d0abeb5a9735695b967053088be42 Mon Sep 17 00:00:00 2001 From: Takashi NATSUME Date: Thu, 27 Sep 2018 17:56:03 +0900 Subject: [PATCH] Add API ref guideline for body text Add guideline for body text in the API reference. Change-Id: Ib03b562ffe189f24293eb77dd0c0ed5ec679172a Partial-Bug: #1793034 --- doc/source/contributor/api-ref-guideline.rst | 174 +++++++++++++++++-- 1 file changed, 163 insertions(+), 11 deletions(-) diff --git a/doc/source/contributor/api-ref-guideline.rst b/doc/source/contributor/api-ref-guideline.rst index 5c6ade5ea327..dd814495149e 100644 --- a/doc/source/contributor/api-ref-guideline.rst +++ b/doc/source/contributor/api-ref-guideline.rst @@ -38,7 +38,13 @@ Structure of inc file Each REST API is described in the text file (\*.inc). The structure of inc file is as follows: -- Title +- Title (Resource name) + + - Introductory text and context + + The introductory text and the context for the resource in question should + be added. This might include links to the API Concept guide, or building + other supporting documents to explain a concept (like versioning). - API Name @@ -46,8 +52,9 @@ The structure of inc file is as follows: - URL - Description - - Normal status code - - Error status code + + See the `Description`_ section for more details. + - Response codes - Request - Parameters @@ -94,6 +101,153 @@ what is in the code. For instance, the title for the section on method "Get Rdp Console" should be "Get Rdp Console (os-getRDPConsole Action)" NOT "Get Rdp Console (Os-Getrdpconsole Action)" +Description +----------- + +The following items should be described in each API. +Or links to the pages describe them should be added. + +* The purpose of the API(s) + + - e.g. Lists, creates, shows details for, updates, and deletes servers. + - e.g. Creates a server. + +* Microversion + + - Deprecated + + - Warning + - Microversion to start deprecation + - Alternatives (superseded ways) and + their links (if document is available) + + - Added + + - Microversion that the API has been added + + - Changed behavior + + - Microversion to change behavior + - Explanation of the behavior + + - Changed HTTP response codes + + - Microversion to change the response code + - Explanation of the response code + +* Warning if direct use is not recommended + + - e.g. This is an admin level service API only designed to be used by other + OpenStack services. The point of this API is to coordinate between Nova + and Neutron, Nova and Cinder (and potentially future services) on + activities they both need to be involved in, such as network hotplugging. + Unless you are writing Neutron or Cinder code you should not be using this API. + +* Explanation about statuses of resource in question + + - e.g. The server status. + + - ``ACTIVE``. The server is active. + +* Supplementary explanation for parameters + + - Examples of query parameters + - Parameters that are not specified at the same time + - Values that cannot be specified. + + - e.g. A destination host is the same host. + +* Behavior + + - Config options to change the behavior and the effect + - Effect to resource status + + - Ephemeral disks, attached volumes, attached network ports and others + - Data loss or preserve contents + + - Scheduler + + - Whether the scheduler choose a destination host or not + +* Policy + + - Default policy (the admin only, the admin or the owner) + - How to change the policy + +* Preconditions + + - Server status + - Task state + - Policy for locked servers + - Quota + - Limited support + + - e.g. Only qcow2 is supported + + - Compute driver support + + - If very few compute drivers support the operation, add a warning and + a link to the support matrix of virt driver. + + - Cases that are not supported + + - e.g. A volume-backed server + +* Postconditions + + - If the operation is asynchronous, + it should be "Asynchronous postconditions". + + - Describe what status/state resource in question becomes by the operation + + - Server status + - Task state + - Path of output file + +* Troubleshooting + + - e.g. If the server status remains ``BUILDING`` or shows another error status, + the request failed. Ensure you meet the preconditions then investigate + the compute node. + +* Related operations + + - Operations to be paired + + - e.g. Start and stop + + - Subsequent operation + + - e.g. "Confirm resize" after "Resize" operation + +* Performance + + - e.g. The progress of this operation depends on the location of + the requested image, network I/O, host load, selected flavor, and other + factors. + +* Progress + + - How to get progress of the operation if the operation is asynchronous. + +* Restrictions + + - Range that ID is unique + + - e.g. HostId is unique per account and is not globally unique. + +* How to avoid errors + + - e.g. The server to get console log from should set + ``export LC_ALL=en_US.UTF-8`` in order to avoid incorrect unicode error. + +* Reference + + - Links to the API Concept guide, or building other supporting documents to + explain a concept (like versioning). + +* Other notices + Response codes ~~~~~~~~~~~~~~ @@ -123,6 +277,12 @@ The description of typical error response codes are as follows: * - 503 - serviceUnavailable(503) +In addition, the following explanations should be described. + +- Condition each normal response code is returned + (If there are multiple normal response codes.) +- Condition each error response code is returned + Parameters ---------- @@ -229,14 +389,6 @@ included. For example:: Examples for multiple microversions should be included in ascending microversion order. -Body ----- - -.. TODO:: - - The guideline for the introductory text and the context for the resource - in question should be added. - Reference =========