book

Designing APIs with Swagger and OpenAPI

Name: Designing APIs with Swagger and OpenAPI
ISBN: 9781617296284

by Lukas Rosenstock, Joshua Ponelat

June 2022

Intermediate to advanced

424 pages

11h 50m

English

Manning Publications

Read now

Unlock full access

inside front cover
Designing APIs with Swagger and OpenAPI
Copyright
dedication
contents
front matter
forewordprefaceacknowledgmentsabout this bookWho should read this bookHow this book is organized: A roadmapAbout the codeliveBook discussion forumOther online resourcesabout the authorsabout the cover illustration
Part 1 Describing APIs
1 Introducing APIs and OpenAPI
1.1 What is an API ecosystem?1.2 Describing things1.2.1 Bridget’s task1.2.2 The potential of Bridget’s solution1.3 What is OpenAPI?1.3.1 Example OpenAPI definition1.4 Where do OpenAPI definitions fit in?1.5 What is Swagger?1.6 What about REST?1.7 When to use OpenAPI1.7.1 For API consumers1.7.2 For API producers1.7.3 For API designers1.8 This bookSummary
2 Getting set up to make API requests
2.1 The problem2.1.1 FarmStall API overview2.1.2 The first two operations of the FarmStall API2.2 Getting set up with Postman2.3 FarmStall API2.4 Our first request2.4.1 Forming a GET request in Postman2.4.2 Verification2.5 Adding a review to the FarmStall API2.5.1 Forming a POST request in Postman2.5.2 Verification2.6 Practice2.6.1 Cat (and other animal) facts API2.6.2 Random avatar API2.6.3 DuckDuckGo’s search engine API2.6.4 Pirate talk API2.7 HTTP for the braveSummary
3 Our first taste of OpenAPI definitions
3.1 The problem3.2 Introducing the OpenAPI specification3.3 A quick refresher on YAML3.3.1 From JSON to YAML3.4 Describing our first operation3.5 Extending our first operationSummary

4 Using Swagger Editor to write OpenAPI definitions
4.1 Introducing Swagger Editor4.1.1 The Editor panel4.1.2 The UI Docs panel4.1.3 The toolbar4.1.4 Persistence4.2 Writing the smallest OpenAPI definition in Swagger Editor4.2.1 The smallest valid OpenAPI definition4.2.2 Writing in Swagger Editor4.2.3 A word on validation4.3 Adding GET /reviews to our definition4.4 Interacting with our API4.4.1 Executing GET /reviews4.4.2 Adding servers to our definition4.4.3 Executing GET /reviews (again)Summary
5 Describing API responses
5.1 HTTP responses5.2 The problem5.3 The mind-blowing world of data schemas5.4 JSON Schema5.4.1 The type field5.4.2 Adding a field to an object5.4.3 The minimum and maximum keywords5.4.4 Number vs. integer5.5 Status codes5.6 Media types (aka MIME)5.7 Describing the GET /reviews response5.7.1 Smallest response in OpenAPI5.7.2 The GET /reviews 200 response body5.7.3 Adding the rating field to our response body5.7.4 Describing message, uuid, and userIdSummary
6 Creating resources
6.1 The problem6.2 Describing POST /reviews with a request body6.2.1 Where to find request bodies6.2.2 Describing the schema for POST /reviews requestBody6.3 Executing operations with request bodies6.3.1 Adding examples to make try-it-out look pretty6.4 Describing GET /reviews/{reviewId} with a path parameter6.4.1 Path parameters6.4.2 Describing the reviewId path parameter6.5 Verifying our reviews are getting createdSummary
7 Adding authentication and authorization
7.1 The problem7.2 Getting set up for authentication7.2.1 Challenge: Describe POST /users7.2.2 Challenge: Describe POST /tokens7.2.3 Solution: Definition changes7.2.4 Verifying we can create users and get a token7.3 Adding the Authorization header7.3.1 How OpenAPI handles authorization7.3.2 Types of authorization (securities) supported in OpenAPI 3.0.x7.3.3 Adding the Authorization header security scheme7.3.4 Adding the security requirements to POST /reviews7.3.5 Using the security feature of try-it-out7.4 Optional security7.5 Other types of security schemas7.6 How to add security schemes in generalSummary
8 Preparing and hosting API documentation
8.1 The problem8.2 Adding metadata to the definition8.3 Writing the description in Markdown8.3.1 Markdown basics8.3.2 Adding a rich text description to the FarmStall API definition8.4 Organizing operations with tags8.4.1 Adding the Reviews tag to GET /reviews8.4.2 Adding descriptions to tags8.4.3 Adding the rest of the tags8.5 Hosting our API documentation using Netlify.com and Swagger UI8.5.1 Preparing Swagger UI with our definition8.5.2 Hosting on Netlify.com8.6 The end of part 1Summary
Part 2 Design-first
9 Designing a web application
9.1 The PetSitter idea9.2 PetSitter project kickoff9.2.1 Additional requirements9.2.2 Team structure9.2.3 API-driven architecture9.2.4 The plan9.3 Domain modeling and APIs9.3.1 Domain modeling for APIs9.3.2 Looking back on FarmStall9.4 A domain model for PetSitter9.4.1 Concepts in the model9.4.2 The User model9.4.3 The Job and Dog models9.5 User stories for PetSitter9.5.1 What are user stories?9.5.2 Collecting user stories9.5.3 Mapping user storiesSummary
10 Creating an API design using OpenAPI
10.1 The problem10.1.1 Converting a domain model to OpenAPI10.1.2 Ensuring reusability10.2 Creating the schemas10.2.1 Starting an OpenAPI file with schemas10.2.2 Referencing common schemas10.2.3 The User schema10.2.4 The Job schema10.2.5 The Dog schema10.2.6 The JobApplication schema10.3 The CRUD approach to API operations10.3.1 Defining API requests and responses10.3.2 From user stories to CRUD design10.4 API operations for PetSitter10.4.1 User operations10.4.2 Job operations10.4.3 JobApplication operationsSummary
11 Building a change workflow around API design-first
11.1 The problem11.2 Communicating and reacting to change11.3 GitHub as our workflow engine11.3.1 A single source of truth11.3.2 Suggesting a change11.3.3 Agreeing on a change11.3.4 A way of viewing changes (based on an older version)11.4 Tying the GitHub workflow together11.4.1 Setting up GitHub and the source of truth11.4.2 Steps in our GitHub workflow11.5 A practical look at the workflow11.5.1 Creating and suggesting DELETE /jobs/{id}11.5.2 Reviewing and accepting changes11.5.3 Comparing older branches to the latest11.5.4 What we’ve doneSummary
12 Implementing frontend code and reacting to changes
12.1 The problem12.2 Setting up Prism12.2.1 Installing Prism12.2.2 Verifying that Prism works12.3 Building a frontend based on a mock server12.3.1 Adding multiple examples into your OpenAPI definition12.3.2 Using examples in Prism12.4 Identifying a missing API operation12.4.1 Due diligence for adding the operation12.4.2 Designing the new operation12.4.3 Choosing which mock data response to get from Prism12.4.4 Formalizing and suggesting the change12.4.5 Extra curl examplesSummary
13 Building a backend with Node.js and Swagger Codegen
13.1 The problem13.2 Introducing Swagger Codegen13.2.1 Client code generation13.2.2 Server code generation13.2.3 Swagger Generator13.3 The backend structure13.3.1 Generating the backend13.3.2 Investigating the structure13.3.3 OpenAPI changes13.4 Updating OpenAPI for the backend13.4.1 Adding operation IDs13.4.2 Tagging API operations13.4.3 Regenerating the backend stubs13.5 Running and testing the backend13.5.1 Testing with Postman13.5.2 Testing input validation13.5.3 Output validation with Prism13.6 Database persistence with Mongoose13.6.1 Another API modification13.6.2 Getting ready to use MongoDB13.6.3 Configuring Mongoose in the project13.6.4 Creating models13.7 Implementing API methodsSummary
14 Integrating and releasing the web application
14.1 The problems14.1.1 Authentication14.1.2 Organizing code14.1.3 Serving both components14.2 Implementing authorization14.2.1 Creating a security scheme14.2.2 Adding a “Login” action14.2.3 Defining operation security14.3 Managing repositories14.3.1 Keeping the existing structure14.3.2 Creating a shared Git repository to implement both components14.3.3 Combining code and API definition in a repository14.3.4 Making the choice and refactoring14.4 Setting up an integrated web server14.4.1 URL design14.4.2 Server setupSummary
Part 3 Extending APIs
15 Designing the next API iteration
15.1 Reviewing the first development sprint15.2 Planning the next sprint15.3 Preparing for new features15.3.1 Reviewing the domain model15.3.2 Reviewing user stories15.4 Improving the developer experience15.4.1 Consistency15.4.2 Error handling15.4.3 Input validation15.4.4 Versioning vs. evolvabilitySummary
16 Designing schemas with composition in OpenAPI
16.1 The problem16.2 Polymorphism and inheritance in domain models16.3 Updating the schemas16.3.1 The Pet schema16.3.2 The Dog schema16.3.3 The Cat schema16.4 Polymorphism and inheritance in OpenAPI16.4.1 Composition inside the Dog and Cat schemas16.4.2 Composition inside the Pet schema16.5 Adding discriminators in OpenAPISummary
17 Scaling collection endpoints with filters and pagination
17.1 The problem17.2 Designing filters17.2.1 Projection filters17.2.2 Selection filters17.2.3 Handling nested schemas17.2.4 Query languages17.2.5 Special conventions17.3 Filters for PetSitter17.3.1 Finding filter fields17.3.2 Adding filters to OpenAPI17.3.3 Making a request17.4 Designing pagination17.4.1 Offset-based and page-based pagination17.4.2 Cursor-based pagination17.5 Pagination for PetSitter17.5.1 Adding pagination to OpenAPI17.5.2 Extending our request example17.6 Designing sorting17.6.1 Single-field sorting17.6.2 Multifield sorting17.6.3 Consistency throughout parameter types17.7 Sorting for PetSitter17.7.1 Finding sorting fields17.7.2 Designing the sort parameter17.7.3 Adding sorting to OpenAPI17.7.4 The final request exampleSummary
18 Supporting the unhappy path: Error handling with problem+json
18.1 The problem18.2 Error categories18.2.1 Finding unhappy paths18.2.2 Common error patterns18.3 Requirements for error responses18.4 The OAS tools format18.5 The problem+json format18.6 Adding error responses to OpenAPI18.6.1 Creating error schemas18.6.2 Adding errors to operations18.7 Error-handling guidance18.7.1 Frontend development18.7.2 Backend developmentSummary
19 Improving input validation with advanced JSON Schema
19.1 The problem19.2 Supported validations19.2.1 Read-only and write-only properties19.2.2 Enforcing number constraints19.2.3 Enforcing string formats19.2.4 Enforcing array constraints19.2.5 Defining enumerations19.2.6 Listing required and optional properties19.2.7 Setting defaults19.3 Updating PetSitter schemas19.3.1 User schema19.3.2 Job schema19.3.3 JobApplication schema19.3.4 Pet, Dog, and Cat schemasSummary
20 Versioning an API and handling breaking changes
20.1 The problem20.2 What is a breaking change?20.3 Releasing a breaking change20.3.1 Coordinated breaking changes20.3.2 Multiple API versions20.3.3 Using media types to version operations20.3.4 Adding and deprecating featuresSummary
21 The API prerelease checklist
21.1 Pros and cons of a public API21.2 The checklist21.3 Getting the API working21.3.1 Unit testing your API21.3.2 End-to-end testing21.4 Documentation21.5 Getting your API consistent21.6 Validation and error reporting21.7 An API roadmap and exposure index21.8 Getting a change strategy21.9 Improving security21.10 Monitoring your API21.10.1 Setting up metric collection21.11 Releasing the APISummary
Appendix A. Swagger 2.0, OpenAPI 3.0, and OpenAPI 3.1
A.1 The main differences between versionsA.2 OpenAPI 2.0 (Swagger 2.0)A.2.1 Non-changesA.2.2 host, basePath, and schemes → serversA.2.3 ResponsesA.2.4 parameter/in-body → requestBodyA.2.5 Components and structureA.2.6 anyOf, oneOfA.3 OpenAPI 3.1A.3.1 JSON Schema 2020-12A.3.2 VocabulariesA.3.3 OpenAPI extending JSON Schema (via a vocabulary)A.3.4 Webhooks
index
inside back cover

Content preview from Designing APIs with Swagger and OpenAPI

18 Supporting the unhappy path: Error handling with problem+json

This chapter covers

Finding and categorizing API errors
The error-handling format from the OAS tools library
The problem+json format
Adding error responses to the PetSitter OpenAPI definition

As we have designed and implemented the PetSitter API, we’ve mostly looked at the happy path, which is when everything works according to plan and things are 200 OK. Obviously we want the interactions between our API and its users to be on this path as often as possible, but we cannot always guarantee that. In this chapter we’ll look at the ways things can go wrong and how to handle those situations.

The OpenAPI definition of an API is a contract that both sides, client and server, have to ...

Become an O’Reilly member and get unlimited access to this title plus top books and audiobooks from O’Reilly and nearly 200 top publishers, thousands of courses curated by job role, 150+ live events each month,
and much more.

Read now

Unlock full access

More than 5,000 organizations count on O’Reilly

O’Reilly covers everything we've got, with content to help us build a world-class technology community, upgrade the capabilities and competencies of our teams, and improve overall team performance as well as their engagement.

Julian F.

Head of Cybersecurity

I wanted to learn C and C++, but it didn't click for me until I picked up an O'Reilly book. When I went on the O’Reilly platform, I was astonished to find all the books there, plus live events and sandboxes so you could play around with the technology.

Addison B.

Field Engineer

I’ve been on the O’Reilly platform for more than eight years. I use a couple of learning platforms, but I'm on O'Reilly more than anybody else. When you're there, you start learning. I'm never disappointed.

Amir M.

Data Platform Tech Lead

I'm always learning. So when I got on to O'Reilly, I was like a kid in a candy store. There are playlists. There are answers. There's on-demand training. It's worth its weight in gold, in terms of what it allows me to do.

Mark W.

Embedded Software Engineer

Principles of Web API Design: Delivering Value with APIs and Microservices

Publisher Resources

ISBN: 9781617296284Publisher Support Publisher Website Errata Page

Cloud Computing

Data Engineering

Data Science

AI & ML

Programming Languages

Software Architecture

IT/Ops

Security

Design

Business

Soft Skills

Designing APIs with Swagger and OpenAPI

by Lukas Rosenstock, Joshua Ponelat

18 Supporting the unhappy path: Error handling with problem+json

Become an O’Reilly member and get unlimited access to this title plus top books and audiobooks from O’Reilly and nearly 200 top publishers, thousands of courses curated by job role, 150+ live events each month,
and much more.