Designing APIs with Swagger and OpenAPI

Designing APIs with Swagger and OpenAPI
brief contents
contents
foreword
preface
acknowledgments
about this book
Who should read this book
How this book is organized: A roadmap
About the code
liveBook discussion forum
Other online resources
about the authors
about the cover illustration
Part 1—Describing APIs
1 Introducing APIs and OpenAPI
1.1 What is an API ecosystem?
1.2 Describing things
1.2.1 Bridget’s task
1.2.2 The potential of Bridget’s solution
1.3 What is OpenAPI?
1.3.1 Example OpenAPI definition
1.4 Where do OpenAPI definitions fit in?
1.5 What is Swagger?
1.6 What about REST?
1.7 When to use OpenAPI
1.7.1 For API consumers
1.7.2 For API producers
1.7.3 For API designers
1.8 This book
Summary
2 Getting set up to make API requests
2.1 The problem
2.1.1 FarmStall API overview
2.1.2 The first two operations of the FarmStall API
2.2 Getting set up with Postman
2.3 FarmStall API
2.4 Our first request
2.4.1 Forming a GET request in Postman
2.4.2 Verification
2.5 Adding a review to the FarmStall API
2.5.1 Forming a POST request in Postman
2.5.2 Verification
2.6 Practice
2.6.1 Cat (and other animal) facts API
2.6.2 Random avatar API
2.6.3 DuckDuckGo’s search engine API
2.6.4 Pirate talk API
2.7 HTTP for the brave
Summary
3 Our first taste of OpenAPI definitions
3.1 The problem
3.2 Introducing the OpenAPI specification
3.3 A quick refresher on YAML
3.3.1 From JSON to YAML
3.4 Describing our first operation
3.5 Extending our first operation
Summary
4 Using Swagger Editor to write OpenAPI definitions
4.1 Introducing Swagger Editor
4.1.1 The Editor panel
4.1.2 The UI Docs panel
4.1.3 The toolbar
4.1.4 Persistence
4.2 Writing the smallest OpenAPI definition in Swagger Editor
4.2.1 The smallest valid OpenAPI definition
4.2.2 Writing in Swagger Editor
4.2.3 A word on validation
4.3 Adding GET /reviews to our definition
4.4 Interacting with our API
4.4.1 Executing GET /reviews
4.4.2 Adding servers to our definition
4.4.3 Executing GET /reviews (again)
Summary
5 Describing API responses
5.1 HTTP responses
5.2 The problem
5.3 The mind-blowing world of data schemas
5.4 JSON Schema
5.4.1 The type field
5.4.2 Adding a field to an object
5.4.3 The minimum and maximum keywords
5.4.4 Number vs. integer
5.5 Status codes
5.6 Media types (aka MIME)
5.7 Describing the GET /reviews response
5.7.1 Smallest response in OpenAPI
5.7.2 The GET /reviews 200 response body
5.7.3 Adding the rating field to our response body
5.7.4 Describing message, uuid, and userId
Summary
6 Creating resources
6.1 The problem
6.2 Describing POST /reviews with a request body
6.2.1 Where to find request bodies
6.2.2 Describing the schema for POST /reviews requestBody
6.3 Executing operations with request bodies
6.3.1 Adding examples to make try-it-out look pretty
6.4 Describing GET /reviews/{reviewId} with a path parameter
6.4.1 Path parameters
6.4.2 Describing the reviewId path parameter
6.5 Verifying our reviews are getting created
Summary
7 Adding authentication and authorization
7.1 The problem
7.2 Getting set up for authentication
7.2.1 Challenge: Describe POST /users
7.2.2 Challenge: Describe POST /tokens
7.2.3 Solution: Definition changes
7.2.4 Verifying we can create users and get a token
7.3 Adding the Authorization header
7.3.1 How OpenAPI handles authorization
7.3.2 Types of authorization (securities) supported in OpenAPI 3.0.x
7.3.3 Adding the Authorization header security scheme
7.3.4 Adding the security requirements to POST /reviews
7.3.5 Using the security feature of try-it-out
7.4 Optional security
7.5 Other types of security schemas
7.6 How to add security schemes in general
Summary
8 Preparing and hosting API documentation
8.1 The problem
8.2 Adding metadata to the definition
8.3 Writing the description in Markdown
8.3.1 Markdown basics
8.3.2 Adding a rich text description to the FarmStall API definition
8.4 Organizing operations with tags
8.4.1 Adding the Reviews tag to GET /reviews
8.4.2 Adding descriptions to tags
8.4.3 Adding the rest of the tags
8.5 Hosting our API documentation using Netlify.com and Swagger UI
8.5.1 Preparing Swagger UI with our definition
8.5.2 Hosting on Netlify.com
8.6 The end of part 1
Summary
Part 2—Design-first
9 Designing a web application
9.1 The PetSitter idea
9.2 PetSitter project kickoff
9.2.1 Additional requirements
9.2.2 Team structure
9.2.3 API-driven architecture
9.2.4 The plan
9.3 Domain modeling and APIs
9.3.1 Domain modeling for APIs
9.3.2 Looking back on FarmStall
9.4 A domain model for PetSitter
9.4.1 Concepts in the model
9.4.2 The User model
9.4.3 The Job and Dog models
9.5 User stories for PetSitter
9.5.1 What are user stories?
9.5.2 Collecting user stories
9.5.3 Mapping user stories
Summary
10 Creating an API design using OpenAPI
10.1 The problem
10.1.1 Converting a domain model to OpenAPI
10.1.2 Ensuring reusability
10.2 Creating the schemas
10.2.1 Starting an OpenAPI file with schemas
10.2.2 Referencing common schemas
10.2.3 The User schema
10.2.4 The Job schema
10.2.5 The Dog schema
10.2.6 The JobApplication schema
10.3 The CRUD approach to API operations
10.3.1 Defining API requests and responses
10.3.2 From user stories to CRUD design
10.4 API operations for PetSitter
10.4.1 User operations
10.4.2 Job operations
10.4.3 JobApplication operations
Summary
11 Building a change workflow around API design–first
11.1 The problem
11.2 Communicating and reacting to change
11.3 GitHub as our workflow engine
11.3.1 A single source of truth
11.3.2 Suggesting a change
11.3.3 Agreeing on a change
11.3.4 A way of viewing changes (based on an older version)
11.4 Tying the GitHub workflow together
11.4.1 Setting up GitHub and the source of truth
11.4.2 Steps in our GitHub workflow
11.5 A practical look at the workflow
11.5.1 Creating and suggesting DELETE /jobs/{id}
11.5.2 Reviewing and accepting changes
11.5.3 Comparing older branches to the latest
11.5.4 What we’ve done
Summary
12 Implementing frontend code and reacting to changes
12.1 The problem
12.2 Setting up Prism
12.2.1 Installing Prism
12.2.2 Verifying that Prism works
12.3 Building a frontend based on a mock server
12.3.1 Adding multiple examples into your OpenAPI definition
12.3.2 Using examples in Prism
12.4 Identifying a missing API operation
12.4.1 Due diligence for adding the operation
12.4.2 Designing the new operation
12.4.3 Choosing which mock data response to get from Prism
12.4.4 Formalizing and suggesting the change
12.4.5 Extra curl examples
Summary
13 Building a backend with Node.js and Swagger Codegen
13.1 The problem
13.2 Introducing Swagger Codegen
13.2.1 Client code generation
13.2.2 Server code generation
13.2.3 Swagger Generator
13.3 The backend structure
13.3.1 Generating the backend
13.3.2 Investigating the structure
13.3.3 OpenAPI changes
13.4 Updating OpenAPI for the backend
13.4.1 Adding operation IDs
13.4.2 Tagging API operations
13.4.3 Regenerating the backend stubs
13.5 Running and testing the backend
13.5.1 Testing with Postman
13.5.2 Testing input validation
13.5.3 Output validation with Prism
13.6 Database persistence with Mongoose
13.6.1 Another API modification
13.6.2 Getting ready to use MongoDB
13.6.3 Configuring Mongoose in the project
13.6.4 Creating models
13.7 Implementing API methods
Summary
14 Integrating and releasing the web application
14.1 The problems
14.1.1 Authentication
14.1.2 Organizing code
14.1.3 Serving both components
14.2 Implementing authorization
14.2.1 Creating a security scheme
14.2.2 Adding a “Login” action
14.2.3 Defining operation security
14.3 Managing repositories
14.3.1 Keeping the existing structure
14.3.2 Creating a shared Git repository to implement both components
14.3.3 Combining code and API definition in a repository
14.3.4 Making the choice and refactoring
14.4 Setting up an integrated web server
14.4.1 URL design
14.4.2 Server setup
Summary
Part 3—Extending APIs
15 Designing the next API iteration
15.1 Reviewing the first development sprint
15.2 Planning the next sprint
15.3 Preparing for new features
15.3.1 Reviewing the domain model
15.3.2 Reviewing user stories
15.4 Improving the developer experience
15.4.1 Consistency
15.4.2 Error handling
15.4.3 Input validation
15.4.4 Versioning vs. evolvability
Summary
16 Designing schemas with composition in OpenAPI
16.1 The problem
16.2 Polymorphism and inheritance in domain models
16.3 Updating the schemas
16.3.1 The Pet schema
16.3.2 The Dog schema
16.3.3 The Cat schema
16.4 Polymorphism and inheritance in OpenAPI
16.4.1 Composition inside the Dog and Cat schemas
16.4.2 Composition inside the Pet schema
16.5 Adding discriminators in OpenAPI
Summary
17 Scaling collection endpoints with filters and pagination
17.1 The problem
17.2 Designing filters
17.2.1 Projection filters
17.2.2 Selection filters
17.2.3 Handling nested schemas
17.2.4 Query languages
17.2.5 Special conventions
17.3 Filters for PetSitter
17.3.1 Finding filter fields
17.3.2 Adding filters to OpenAPI
17.3.3 Making a request
17.4 Designing pagination
17.4.1 Offset-based and page-based pagination
17.4.2 Cursor-based pagination
17.5 Pagination for PetSitter
17.5.1 Adding pagination to OpenAPI
17.5.2 Extending our request example
17.6 Designing sorting
17.6.1 Single-field sorting
17.6.2 Multifield sorting
17.6.3 Consistency throughout parameter types
17.7 Sorting for PetSitter
17.7.1 Finding sorting fields
17.7.2 Designing the sort parameter
17.7.3 Adding sorting to OpenAPI
17.7.4 The final request example
Summary
18 Supporting the unhappy path: Error handling with problem+json
18.1 The problem
18.2 Error categories
18.2.1 Finding unhappy paths
18.2.2 Common error patterns
18.3 Requirements for error responses
18.4 The OAS tools format
18.5 The problem+json format
18.6 Adding error responses to OpenAPI
18.6.1 Creating error schemas
18.6.2 Adding errors to operations
18.7 Error-handling guidance
18.7.1 Frontend development
18.7.2 Backend development
Summary
19 Improving input validation with advanced JSON Schema
19.1 The problem
19.2 Supported validations
19.2.1 Read-only and write-only properties
19.2.2 Enforcing number constraints
19.2.3 Enforcing string formats
19.2.4 Enforcing array constraints
19.2.5 Defining enumerations
19.2.6 Listing required and optional properties
19.2.7 Setting defaults
19.3 Updating PetSitter schemas
19.3.1 User schema
19.3.2 Job schema
19.3.3 JobApplication schema
19.3.4 Pet, Dog, and Cat schemas
Summary
20 Versioning an API and handling breaking changes
20.1 The problem
20.2 What is a breaking change?
20.3 Releasing a breaking change
20.3.1 Coordinated breaking changes
20.3.2 Multiple API versions
20.3.3 Using media types to version operations
20.3.4 Adding and deprecating features
Summary
21 The API prerelease checklist
21.1 Pros and cons of a public API
21.2 The checklist
21.3 Getting the API working
21.3.1 Unit testing your API
21.3.2 End-to-end testing
21.4 Documentation
21.5 Getting your API consistent
21.6 Validation and error reporting
21.7 An API roadmap and exposure index
21.8 Getting a change strategy
21.9 Improving security
21.10 Monitoring your API
21.10.1 Setting up metric collection
21.11 Releasing the API
Summary
Appendix—Swagger 2.0, OpenAPI 3.0, and OpenAPI 3.1
A.1 The main differences between versions
A.2 OpenAPI 2.0 (Swagger 2.0)
A.2.1 Non-changes
A.2.2 host, basePath, and schemes → servers
A.2.3 Responses
A.2.4 parameter/in-body → requestBody
A.2.5 Components and structure
A.2.6 anyOf, oneOf
A.3 OpenAPI 3.1
A.3.1 JSON Schema 2020-12
A.3.2 Vocabularies
A.3.3 OpenAPI extending JSON Schema (via a vocabulary)
A.3.4 Webhooks
index
API endpoints
A
B
C
D
E
F
G
H
I
J
L
M
N
O
P
Q
R
S
T
U
V
W
X
Y