5.3 Explanation format for an API
The following lists sections to explain an API. Some sections are applicable only for some APIs, but not for others.
- Description
-
Describes what you can do with the API.
- Execution permissions
-
Lists permissions and roles required to run the API.
- API version
-
Indicates the API version.
- Format
-
Describes API request and response formats.
- Parameters
-
Describes parameters to be specified in the request message body.
- Status codes
-
Describes status codes that are returned as a response to the API that is run over the http or https protocol. For details on the status codes when an error occurs before an API is run, see 5.2.5(1) Status codes.
- Return values
-
Describes return values that are returned by the API.
- Examples
-
Describes request and response examples to use the API.
Note that examples in this chapter use the http protocol. If you want to use the https protocol, you need to replace HTTP with HTTPS.