6 Describing HTTP operations with OpenAPI

 

This chapter covers

  • Introduction to the OpenAPI Specification
  • Describing resource paths
  • Describing HTTP operations
  • Describing HTTP operations’ inputs and outputs

Our API designer’s job could be considered done. We have designed a versatile REST API exposing capabilities that meet the needs identified in the Define stage of the API lifecycle. But we described the programming interface using a spreadsheet; it could also have been a word processor document or a wiki page. These formats are not made for this task; authoring and maintaining such documents can be complex and error-prone. A more efficient way is to use an API specification, a standard format for describing APIs. The OpenAPI Specification is the most common for REST APIs, simplifying design, reducing errors, and facilitating discussions while enabling more than just describing APIs and benefiting the rest of the API lifecycle.

After introducing OpenAPI, this chapter shows how the “Describe the programming interface” step of the API design process parallels “Design the programming interface.” Then we discuss how to author OpenAPI documents and provide an overview of the steps to create an OpenAPI document describing the HTTP operations as we design them. We also go through these steps to describe the API’s resources and operations and their inputs and outputs. The following chapter describes data models as we design them.

6.1 Overview of describing the programming interface

6.1.1 Introducing the OpenAPI Specification

6.1.2 Using OpenAPI during design

6.1.3 Introducing the YAML format

6.1.4 Contrasting an OpenAPI document with our API spreadsheet

6.1.5 Describing the programming interface while designing it

6.2 Authoring OpenAPI documents

6.2.1 Introducing the specification-first and code-first approaches

6.2.2 Contrasting the specification-first and code-first approaches

6.2.3 Picking an OpenAPI editor

6.2.4 Choosing an OpenAPI version

6.2.5 Choosing between JSON and YAML

6.3 Describing HTTP operations with OpenAPI

6.4 Describing resource paths

6.4.1 Initiating an OpenAPI document

6.4.2 Describing a path

6.4.3 Describing a path with path parameters

6.5 Describing operations