فهرست مطالب

• Cover
• Title Page
• Copyright
• Contributors
• Table of Contents
• Preface
• Part 1—Describing APIs
• Chapter 1: Introducing APIs and OpenAPI
• 1.1 What is an API ecosystem?
• 1.2 Describing things
• 1.3 What is OpenAPI?
• 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.8 This book
• Summary
• Chapter 2: Getting set up to make API requests
• 2.1 The problem
• 2.2 Getting set up with Postman
• 2.3 FarmStall API
• 2.4 Our first request
• 2.5 Adding a review to the FarmStall API
• 2.6 Practice
• 2.7 HTTP for the brave
• Summary
• Chapter 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.4 Describing our first operation
• 3.5 Extending our first operation
• Summary
• Chapter 4: Using Swagger Editor to write OpenAPI definitions
• 4.1 Introducing Swagger Editor
• 4.2 Writing the smallest OpenAPI definition in Swagger Editor
• 4.3 Adding GET /reviews to our definition
• 4.4 Interacting with our API
• Summary
• Chapter 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.5 Status codes
• 5.6 Media types (aka MIME)
• 5.7 Describing the GET /reviews response
• Summary
• Chapter 6: Creating resources
• 6.1 The problem
• 6.2 Describing POST /reviews with a request body
• 6.3 Executing operations with request bodies
• 6.4 Describing GET /reviews/{reviewId} with a path parameter
• 6.5 Verifying our reviews are getting created
• Summary
• Chapter 7: Adding authentication and authorization
• 7.1 The problem
• 7.2 Getting set up for authentication
• 7.3 Adding the Authorization header
• 7.4 Optional security
• 7.5 Other types of security schemas
• 7.6 How to add security schemes in general
• Summary
• Chapter 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.4 Organizing operations with tags
• 8.5 Hosting our API documentation using Netlify.com and Swagger UI
• 8.6 The end of part 1
• Summary
• Part 2—Design-first
• Chapter 9: Designing a web application
• 9.1 The PetSitter idea
• 9.2 PetSitter project kickoff
• 9.3 Domain modeling and APIs
• 9.4 A domain model for PetSitter
• 9.5 User stories for PetSitter
• Summary
• Chapter 10: Creating an API design using OpenAPI
• 10.1 The problem
• 10.2 Creating the schemas
• 10.3 The CRUD approach to API operations
• 10.4 API operations for PetSitter
• Summary
• Chapter 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.4 Tying the GitHub workflow together
• 11.5 A practical look at the workflow
• Summary
• Chapter 12: Implementing frontend code and reacting to changes
• 12.1 The problem
• 12.2 Setting up Prism
• 12.3 Building a frontend based on a mock server
• 12.4 Identifying a missing API operation
• Summary
• Chapter 13: Building a backend with Node.js and Swagger Codegen
• 13.1 The problem
• 13.2 Introducing Swagger Codegen
• 13.3 The backend structure
• 13.4 Updating OpenAPI for the backend
• 13.5 Running and testing the backend
• 13.6 Database persistence with Mongoose
• 13.7 Implementing API methods
• Summary
• Chapter 14: Integrating and releasing the web application
• 14.1 The problems
• 14.2 Implementing authorization
• 14.3 Managing repositories
• 14.4 Setting up an integrated web server
• Summary
• Part 3—Extending APIs
• Chapter 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.4 Improving the developer experience
• Summary
• Chapter 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.4 Polymorphism and inheritance in OpenAPI
• 16.5 Adding discriminators in OpenAPI
• Summary
• Chapter 17: Scaling collection endpoints with filters and pagination
• 17.1 The problem
• 17.2 Designing filters
• 17.3 Filters for PetSitter
• 17.4 Designing pagination
• 17.5 Pagination for PetSitter
• 17.6 Designing sorting
• 17.7 Sorting for PetSitter
• Summary
• Chapter 18: Supporting the unhappy path: Error handling with problem+json
• 18.1 The problem
• 18.2 Error categories
• 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.7 Error-handling guidance
• Summary
• Chapter 19: Improving input validation with advanced JSON Schema
• 19.1 The problem
• 19.2 Supported validations
• 19.3 Updating PetSitter schemas
• Summary
• Chapter 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
• Summary
• Chapter 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.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.11 Releasing the API
• Summary
• Appendix—Swagger 2.0, OpenAPI 3.0, and OpenAPI 3.1
• Index