Operation

Use this section to describe an operation available for a resource collection. The section structure consists of the following elements:

Request — an HTTP method required to invoke the operation and define the resource endpoint.

Provide an HTTP request, request headers and a request body for the HTTP method:

HTTP request — the request URL.

Even if the product REST API is served over HTTPS, you must still use the HTTP Request heading. HTTP Request is the official term used in REST API documentation. HTTPS (Hyper Text Transfer Protocol Secure) is just a secure version of HTTP.

Request headers — a list of request headers required for the request.

For each header, specify whether it is required or optional, define its possible values and provide a short description.

Request body — parameters or properties that a user must send in the request body.

Include this subsection to do either of the following:

List parameters required for the request. For each parameter, specify its type and provide a short description.
List properties required for the request. For each property, specify its type and provide a short description.

Response — the expected response.

Begin the subsection with the following generic introductory phrase: The server returns the following response to the client. Then, provide a response code and response body.

Response code — the response code returned by a successfully completed operation.
[Optional] Response body — a description of the output; applies only if the response body is not empty.

Example — an example of a user request and a server response.