Customer-facing and internal APIs have become the most common way to integrate the components of web-based software. Using standards like OpenAPI, you can provide reliable, easy-to-use interfaces that allow other developers safe, controlled access to your software. Designing APIs with Swagger and OpenAPI is a hands-on primer to properly designing and describing your APIs using the most widely-adopted standard.
4 Using SwaggerEditor to write OpenAPI definitions
5 Describing API responses
6 Creating resources
7 Getting and using API Tokens
8 GET requests with path and query parameters
9 Using POST and JSON bodies
10 Our first API definition!
11 The formation of our idea
12 Data modelling ( ie: resources )
13 Writing down our resources
14 Resources and Operations
15 Putting our ideas into an API definition
19 Authorization / Authentication
20 Hitting Limits in Design
21 Part Summary
22 Sharing the documentation
23 Generating Code Overview
24 Bootstrapping a service based on an API
25 Building a service that is driven by an API
26 Generating clients for many different languages
27 Building your own Code Generation templates
28 Validation layer
29 Taking a look at API usage in the wild
30 Wrap up
About the Technology
Modern web applications are made of multiple components, services, and servers connected through APIs, often using HTTP and REST as their primary interfaces. These architectures rely on APIs that allow access to the functionality of a component without requiring developers to understand the details of how it was implemented. The OpenAPI specification standardizes how you describe RESTful APIs. OpenAPI is vendor-neutral and has been adopted by big tech companies such as Google, Microsoft, and Amazon.
About the book
Designing APIs with Swagger and OpenAPI is a hands-on primer for describing, planning and designing web APIs. Core Swagger contributor Josh Ponelat introduces you to a design-first paradigm that will teach you the best practices for describing and designing RESTful APIs using OpenAPI and Swagger. You’ll build upon progressively-enhanced examples as you learn to describe an API and then extend it in the kind of scenarios you’d encounter in the real world. You’ll practice skills for assessing business needs, gathering requirements, and working with a cross-functional team. And as you go, you’ll use the popular Open Source tools to define APIs, generate documentation, and build other developer-friendly components like mocks, server stubs, and client SDKs.
OpenAPI syntax and structure
Using Swagger and OSS tooling to create OpenAPI definitions
Automating processes and generating code
Working with cross-functional teams
About the reader
Web developers who need to build APIs for their teams and customers.
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.