Designing APIs with Swagger and OpenAPI
Joshua S. Ponelat
  • MEAP began August 2019
  • Publication in Spring 2020 (estimated)
  • ISBN 9781617296284
  • 400 pages (estimated)
  • printed in black & white
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.
Table of Contents detailed table of contents

Part 1

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.4 Where do OpenAPI definitions fit in ?

1.5 And what is Swagger?

1.6 What about REST?

1.7 Where to use OpenAPI

1.7.1 When speed matters

1.7.2 Internal networks

1.8 Good APIs

1.9 This book

1.10 Summary

2 Getting set up to make API Requests

2.1 The problem

2.2 Getting set up with Postman

2.2.1 Installing Postman

2.3 FarmStall API

2.4 Our first request!

2.4.1 Forming the Request in Postman

2.4.2 Verification

2.5 Adding a Review to the FarmStall API

2.5.1 Verification

2.6 Practice

2.6.1 Fun API requests to make

2.7 Summary

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

3.6 Summary

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!

Part 2

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

16 Errors

18 Documentation

19 Authorization / Authentication

20 Hitting Limits in Design

21 Part Summary

Part 3

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.

What's inside

  • 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.

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.

Manning Early Access Program (MEAP) Read chapters as they are written, get the finished eBook as soon as it’s ready, and receive the pBook long before it's in bookstores.
MEAP combo $59.99 pBook + eBook + liveBook
MEAP eBook $47.99 pdf + ePub + kindle + liveBook
Prices displayed in rupees will be charged in USD when you check out.

placing your order...

Don't refresh or navigate away from the page.

FREE domestic shipping on three or more pBooks