Designing APIs with Swagger and OpenAPI / Joshua S. Ponelat and Lukas L. Rosenstock ; foreword by Tony Tam.

Format:

Book

Author/Creator:

Ponelat, Joshua, author.

Rosenstock, Lukas L., author.

Contributor:

Tam, Tony, writer of foreword.

Language:

English

Subjects (All):

Application program interfaces (Computer software).

Application software--Development.

Application software.

Physical Description:

1 online resource (378 pages)

Place of Publication:

Shelter Island, New York : Manning Publications, [2022]

Summary:

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.

Contents:

Intro

inside front cover

Designing APIs with Swagger and OpenAPI

Copyright

dedication

contents

front matter

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

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

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)

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

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

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

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

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

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

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

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

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

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

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

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.

Notes:

Description based on print version record.

Includes bibliographical references and index.

Includes index.

ISBN:

9781638352273

1638352275

OCLC:

1331409013