Designing APIs with Swagger and OpenAPI

by Joshua S. Ponelat, Lukas L. Rosenstock

Overview

Follow real-world API projects from concept to production, and learn hands-on how to describe and design APIs using OpenAPI.

In Designing APIs with Swagger and OpenAPI you will learn how to:

Understand OpenAPI syntax and structure
Use Swagger and other tooling to create OpenAPI definitions
Design authentication and authorization
Turn an OpenAPI description into online documentation
Automate processes and generating code
Iterate an API design with user stories
Build a frontend against a mock server
Generate backend code with Swagger Codegen
Versioning an API and dodging breaking changes
Work with cross-functional teams

Designing APIs with Swagger and OpenAPI is a comprehensive guide to designing and describing your first RESTful API using the most widely adopted standards. Following expert instruction from Swagger core contributor Josh Ponelat and API consultant Lukas Rosenstock, you’ll spend each chapter progressively expanding the kind of APIs you’ll want to build in the real world. You’ll utilize OpenAPI and Swagger to help automate your workflow, and free up your time to work on more exciting features. Learn the syntax and structure of OpenAPI definitions, create and iterate on an API design with common tools, and release your API to the public.

Purchase of the print book includes a free eBook in PDF, Kindle, and ePub formats from Manning Publications.

About the technology
Create web APIs that customers and developers will love! Using Swagger, a collection of tools for defining and documenting REST APIs, you will build safe, controlled access to your software. And because Swagger implements the vendor-neutral OpenAPI specification, you’ll be building to the same standards adopted by Google, Microsoft, and Amazon.

About the book
Designing APIs with Swagger and OpenAPI introduces a design-first approach. Written for developers new to API design, it follows the lifecycle of an API project from concept to production. You’ll explore the dos and don’ts of APIs through progressively complete examples. You’ll get hands-on experience designing APIs for specific business needs, using open source tools to generate documentation, and building developer-friendly components like mocks and client SDKs.

What's inside

OpenAPI syntax and structure
Using Swagger to create OpenAPI definitions
Automating processes and generating code
Working with cross-functional teams

About the reader
For web developers. No prior knowledge of Swagger or OpenAPI required.

About the author
Josh Ponelat is the Swagger Open Source lead at SmartBear. Lukas Rosenstock is an independent software developer and API consultant.

Table of Contents
PART 1 DESCRIBING APIS
1 Introducing APIs and OpenAPI
2 Getting set up to make API requests
3 Our first taste of OpenAPI definitions
4 Using Swagger Editor to write OpenAPI definitions
5 Describing API responses
6 Creating resources
7 Adding authentication and authorization
8 Preparing and hosting API documentation
PART 2 DESIGN-FIRST
9 Designing a web application
10 Creating an API design using OpenAPI
11 Building a change workflow around API design–first
12 Implementing frontend code and reacting to changes
13 Building a backend with Node.js and Swagger Codegen
14 Integrating and releasing the web application
PART 3 EXTENDING APIS
15 Designing the next API iteration
16 Designing schemas with composition in OpenAPI
17 Scaling collection endpoints with filters and pagination
18 Supporting the unhappy path: Error handling with problem+json
19 Improving input validation with advanced JSON Schema
20 Versioning an API and handling breaking changes
21 The API prerelease checklist

Product Details

ISBN-13:	9781617296284
Publisher:	Manning
Publication date:	07/05/2022
Pages:	424
Product dimensions:	7.38(w) x 9.25(h) x 1.00(d)

About the Author

Josh Ponelat is a senior architect working with the Swagger/OpenAPI team at SmartBear. He’s based out of Plettenberg Bay, South Africa with his two labradors.

Lukas Rosenstock is an independent software developer, technical writer, API consultant, and entrepreneur who has a decade of experience working in and with startups.

Table of Contents

Foreword xix

Preface xx

Acknowledgments xxii

About this book xxiii

About the authors xxvi

About the cover illustration xxvii

Part 1 Describing APIs 1

1 Introducing APIs and OpenAPI 3

1.1 What is an API ecosystem? 3

1.2 Describing things 4

Bridget's task 4

The potential of Bridget's solution 5

1.3 What is OpenAPI? 5

Example OpenAPI definition 6

1.4 Where do OpenAPI definitions fit in? 7

1.5 What is Swagger? 8

1.6 What about REST? 9

1.7 When to use OpenAPI 10

For API consumers 10

For API producers 11

For API designers 11

1.8 This book 11

2 Getting set up to make API requests 13

2.1 The problem 14

FarmStall API overview 14

The first two operations of the FarmSlall API 14

2.2 Getting set up with Postman 15

2.3 FarmStall API 16

2.4 Our first request 16

Forming a GET request in Postman 17

Verification 18

2.5 Adding a review to the FarmStall API 18

Forming a POST request in Postman 19

Verification 21

2.6 Practice 21

Cat (and other animal) facts API 21

Random avatar API 22

DucWuckGo's search engine API 22

Pirate talk API 22

2.7 HTTP for the brave 23

3 Our first taste of OpenAPI definitions 26

3.1 The problem 28

3.2 Introducing the OpenAPI specification 29

3.3 A quick refresher on YAML 29

From JSON to YAML 31

3.4 Describing our first operation 32

3.5 Extending our first operation 33

4 Using Swagger Editor to write OpenAPI definitions 35

4.1 Introducing Swagger Editor 37

The Editor panel 37

The UI Docs panel 37

The toolbar 38

Persistence 38

4.2 Writing the smallest OpenAPI definition in Swagger Editor 38

The smallest valid OpenAPI definition 38

Writing in Swagger Editor 39

A word on validation 40

4.3 Adding GET /reviews to our definition 41

4.4 Interacting with our API 42

Executing GET /reviews 43

Adding servers to our definition 44

Executing GET/reviews (again) 45

5 Describing API responses 48

5.1 HTTP responses 49

5.2 The problem 50

5.3 The mind-blowing world of data schemas 51

5.4 JSON Schema 51

The type field 52

Adding a field to an object 53

The minimum and maximum keywords 53

Number vs. integer 54

5.5 Status codes 55

5.6 Media types (aka MIME) 56

5.7 Describing the GET /reviews response 57

Smallest response in OpenAPI 57

The GET/reviews 200 response body 57

Adding the rating field to our response-body 58

Describing message, uuid, and userld 59

6 Creating resources 64

6.1 The problem 65

6.2 Describing POST /reviews with a request body 66

Where to find request bodies 69

Describing the schema for POST /reviews requestBody 70

6.3 Executing operations with request bodies 71

Adding examples to make try-it-out look pretty 74

6.4 Describing GET /reviews/{reviewld} with a path parameter 75

Path parameters 76

Describing the reviewld path parameter 77

6.5 Verifying our reviews are getting created 78

7 Adding authentication and authorization 82

7.1 The problem 84

7.2 Getting set up for authentication 85

Challenge: Describe POST /users 86

Challenge: Describe POST /tokens 86

Solution: Definition changes 88

Verifying we can create users and get a token 89

7.3 Adding the Authorization header 91

How OpenAPIhandles authorization 92

Types of authorization (securities) supported in OpenAPI 3.0.x 92

Adding the Authorization header security scheme 93

Adding the security requirements to POST /reviews 94

Using the security feature of try-it-out 94

7.4 Optional security 96

7.5 Other types of security schemas 97

7.6 How to add security schemes in general 97

8 Preparing and hosting API documentation 99

8.1 The problem 100

8.2 Adding metadata to the definition 103

8.3 Writing the description in Markdown 105

Markdown basics 106

Adding a rich text description to the FarmStall API definition 108

8.4 Organizing operations with tags 111

Adding the Reviews tag to GET/reviews 112

Adding descriptions to tags 112

Adding the rest of the tags 113

8.5 Hosting our API documentation using Netlify.com and Swagger UI 114

Preparing Swagger UI with our definition 115

Hosting on Netlify.com 116

8.6 The end of part 1 120

Part 2 Design-First 121

9 Designing a web application 123

9.1 The PetSitter idea 124

9.2 PetSitter project kickoff 124

Additional requirements 124

Team structure 125

API-driven architecture 126

The plan 127

9.3 Domain modeling and APIs 128

Domain modeling for APIs 130

Looking back on FarmStall 130

9.4 A domain model for PetSitter 131

Concepts in the model 131

The User model 132

The Job and Dog models 133

9.5 User stories for PetSitter 134

What are user stories? 134

Collecting user stories 134

Mapping user stories 136

10 Creating an API design using OpenAPI 142

10.1 The problem 143

Converting a domain model to OpenAPI 143

Ensuring reusability 144

10.2 Creating the schemas 145

Starting an OpenAPI file with schemas 145

Referencing common schemas 146

The User schema 146

The Job schema 148

The Dog schema 150

The JobApplication schema 151

10.3 The CRUD approach to API operations 152

Defining API requests and responses 154

From user stories to CRUD design 156

10.4 API operations for PetSitter 156

User operations 156

Job operations 159

JobApplication operations 163

11 Building a change workflow around API design-first 168

11.1 The problem 169

11.2 Communicating and reacting to change 171

11.3 GitHub as our workflow engine 172

A single source of truth 173

Suggesting a change 173

Agreeing on a change 173

A way of viewing changes (based on an older version) 174

11.4 Tying the GitHub workflow together 175

Setting up GitHub and the source of truth 175

Steps in our GitHub workflow 176

11.5 A practical look at the workflow 177

Creating and suggesting DELETE /jobs/ {id} 177

Reviewing and accepting changes 178

Comparing older branches to the latest 179

What we've done 180

12 Implementing frontend code and reacting to changes 182

12.1 The problem 183

12.2 Setting up Prism 183

Installing Prism 183

Verifying that Prism works 184

12.3 Building a frontend based on a mock server 185

Adding multiple examples into your OpenAPI definition 187

Using examples in Prism 188

12.4 Identifying a missing API operation 189

Due diligence for adding the operation 190

Designing the new operation 190

Choosing which mock data response to get from Prism 193

Formalizing and suggesting the change 195

Extra curl examples 196

13 Building a backend with Node.js and Swagger Codegen 198

13.1 The problem 199

13.2 Introducing Swagger Codegen 199

Client code generation 200

Server code generation 200

Swagger Generator 200

13.3 The backend structure 201

Generating the backend 201

Investigating the structure 201

OpenAPI changes 203

13.4 Updating OpenAPI for the backend 204

Adding operation IDs 204

Tagging API operations 206

Regenerating the backend stubs 208

13.5 Running and testing the backend 209

Testing with Postman 209

Testing input validation 210

Output validation with Prism 211

13.6 Database persistence with Mongoose 212

Another API modification 213

Getting ready to use MongoDB 214

Configuring Mongoose in the project 214

Creating models 214

13.7 Implementing API methods 218

14 Integrating and releasing the web application 221

14.1 The problems 222

Authentication 222

Organizing code 223

Serving both components 224

14.2 Implementing authorization 225

Creating a security scheme 225

Adding a "Login" action 226

Defining operation security 229

14.3 Managing repositories 231

Keeping the existing structure 231

Creating a shared Git repository to implement both components 231

Combining code and API definition in a repository 231

Making the choice and refactoring 232

14.4 Setting up an integrated web server 232

URL design 232

Server setup 234

Part 3 Extending APIs 237

15 Designing the next API iteration 239

15.1 Reviewing the first development sprint 240

15.2 Planning the next sprint 241

15.3 Preparing for new features 242

Reviewing the domain model 243

Reviewing user stories 245

15.4 Improving the developer experience 248

Consistency 250

Error handling 250

Input validation 250

Versioning vs. evolvability 251

16 Designing schemas with composition in OpenAPI 253

16.1 The problem 254

16.2 Polymorphism and inheritance in domain models 257

16.3 Updating the schemas 259

The Pet schema 261

The Dog schema 261

The Cat schema 262

16.4 Polymorphism and inheritance in OpenAPI 262

Composition inside the Dog and Cat schemas 264

Composition inside the Pet schema 266

16.5 Adding discriminators in OpenAPI 268

17 Scaling collection endpoints with filters and pagination 273

11.1 The problem 274

17.1 Designing filters 276

Projection filters 277

Selection filters 277

Handling nested schemas 280

Query languages 281

Special conventions 281

17.3 Filters for PetSitter 282

Finding filter fields 282

Adding filters to OpenAPI 286

Making a request 290

17.4 Designing pagination 290

Offset-based and page-based pagination 291

Cursor-based pagination 293

17.5 Pagination for PetSitter 294

Adding pagination to OpenAPI 295

Extending our request example 297

17.6 Designing sorting 297

Single-field sorting 298

Multifield sorting 299

Consistency throughout parameter types 299

17.7 Sorting for PetSitter 300

Finding sorting fields 300

Designing the sort parameter 301

Adding sorting to OpenAPI 301

The final request example 302

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

18.1 The problem 305

18.2 Error categories 306

Finding unhappy paths 307

Common error patterns 309

18.3 Requirements for error responses 309

18.4 The OAS tools format 312

18.5 The problem+json format 314

18.6 Adding error responses to OpenAPI 316

Creating error schemas 317

Adding errors to operations 318

18.7 Error-handling guidance 320

Frontend development 320

Backend development 322

19 Improving input validation with advanced JSON Schema 324

19.1 The problem 325

19.2 Supported validations 326

Read-only and write-only properties 326

Enforcing number constraints 328

Enforcing string formats 328

Enforcing array constraints 330

Defining enumerations 331

Listing required and optional properties 331

Setting defaults 332

19.3 Updating PetSitter schemas 332

User schema 333

Job schema 335

Job Application schema 336

Pet, Dog, and Cat schemas 337

20 Versioning an API and handling breaking changes 339

20.1 The problem 340

20.2 What is a breaking change? 341

20.3 Releasing a breaking change 341

Coordinated breaking changes 342

Multiple API versions 343

Using media types to version operations 346

Adding and deprecating features 349

The API prerelease checklist 353

21.1 Pros and cons of a public API 353

21.2 The checklist 354

21.3 Getting the API working 356

Unit testing your API 356

End-to-end testing 357

21.4 Documentation 360

21.5 Getting your API consistent 362

21.6 Validation and error reporting 363

21.7 An API roadmap and exposure index 363

21.8 Getting a change strategy 366

21.9 Improving security 366

21.10 Monitoring your API 368

Setting up metric collection 368

21.11 Releasing the API 369

Appendix Swagger 2.0, OpenAPI 3.0, and OpenAPI 3.1 371

Index 383