The previous page showed the minimal structure of an OpenAPI Description (OAD) but did not add any operation to the API. This page explains how to do it.
API Endpoints (also called Operations or Routes) are called Paths in the OAS. The Paths Object, accessible through the
paths field in the root OpenAPI Object, is the container for all operations supported by the API:
Every field in the Paths Object is a Path Item Object describing one API endpoint. Fields are used instead of an Array because they enforce endpoint name uniqueness at the syntax level (any JSON or YAML parser can detect mistakes without requiring an OpenAPI validator).
Paths must start with a forward slash
/ since they are directly appended to the server URL (described in the API Servers page) to construct the full endpoint URL.
The Tic Tac Toe sample API is used in this guide to exemplify each concept and it is built piece by piece as the guide progresses. Here’s the first snippet already containing a single endpoint:
openapi: 3.1.0 info: title: Tic Tac Toe description: | This API allows writing down marks on a Tic Tac Toe board and requesting the state of the board or of individual squares. version: 1.0.0 paths: /board: ...
The Path Item Object describes the HTTP operations that can be performed on a path with a separate Operation Object for each one. Allowed operations match HTTP methods names like
delete, to list the most common (find the complete list in the Path Item Object specification).
This object also accepts common properties for all operations on the path like
description. The details of each operation are given in each child Operation object.
paths: /board: get: ... put: ...
Besides giving the operation a
summary and a
description, the Operation Object basically describes the operation’s parameters, payload and possible server responses. The rest of this page explains the
responses field, whereas parameters and payload are dealt with in another page.
paths: /board: get: summary: Get the whole board description: Retrieves the current state of the board and the winner. parameters: ... responses: ...
The Responses Object is a container for the expected answers the server can give to this request. Each field name is an HTTP response code enclosed in quotation marks and its value is a Response Object (note there is no ‘s’ at the end) containing details about the response.
At least one response must be given and it is recommended that it corresponds to the success case (typically HTTP response code 200). 5 wildcards are allowed:
5XX (explicit codes take preference over wildcards).
paths: /board: get: responses: "200": ... "404": ...
The Response Object contains a mandatory
description of the meaning of the response in the context of this operation, complementing the sense of the HTTP response codes (which are generic in nature). This helps developers understand better how to react to this particular code.
The most important field, though, is
content because it describes the possible payloads of the response. Due to its complexity, this field’s format is detailed next, in its own page.
paths: /board: get: responses: "200": description: Everything went fine. content: ...
Here’s a fragment of the example, containing only the objects that have been described so far in the guide. At this point the reader should be able to understand every line of this snippet.
openapi: 3.1.0 info: title: Tic Tac Toe description: | This API allows writing down marks on a Tic Tac Toe board and requesting the state of the board or of individual squares. version: 1.0.0 paths: # Whole board operations /board: get: summary: Get the whole board description: Retrieves the current state of the board and the winner. responses: "200": description: "OK" content: ...
The complete OpenAPI Description can be found in the Tic Tac Toe sample API.
This page has shown how to specify endpoints (
paths), their available operations (
put, …) and their possible outcomes (
The next page shows how to specify the
content of the responses.