Book Review: “Designing APIs with Swagger and OpenAPI”

Disclaimer: this post includes affiliate links; I may receive compensation if you purchase the book from the different links provided in this post.

This review is about Designing APIs with Swagger and OpenAPI by Joshua S. Ponelat and Lukas L. Rosenstock from Manning.

I’m continuing my API journey by reading books, viewing relevant YouTube videos, and reading relevant IETF RFCs.

Today is a book review.


21 chapters
$38.39 (eBook)


Part 1: Describing APIs

Introducing APIs and OpenAPI
Getting set up to make API requests
Our first taste of OpenAPI definitions
Using Swagger Editor to write OpenAPI definitions
Describing API responses
Creating resources
Adding authentication and authorization
Preparing and hosting API documentation

Part 2: Design first

Designing a web application
Creating an API design using OpenAPI
Building a change workflow around API design–first
Implementing frontend code and reacting to changes
Building a backend with Node.js and Swagger Codegen
Integrating and releasing the web application

Part 3: Extending APIs

Designing the next API iteration
Designing schemas with composition in OpenAPI
Scaling collection endpoints with filters and pagination
Supporting the unhappy path: Error handling with problem+json
Improving input validation with advanced JSON Schema
Versioning an API and handling breaking changes
The API prerelease checklist

The book goes through designing a complete API via a demo project, the Farmstall API.

Pros and cons

The review is concise, to say the least.

The book’s main benefit is also its main issue: it focuses on beginners. Everything is very detailed. For example, the authors dedicated chapter 11 to explaining Git’s basics.

I’m not an API expert, but I didn’t learn anything. Hence, I don’t have a lot to say.


If you’re a true newbie, i.e., you know nothing about HTTP, requests and responses, OpenAPI, and Postman, this book is for you. It goes into great detail in explaining everything from scratch.

If you have more than a passing familiarity with any of the above, I’m afraid it will be a loss of your money and time.

Originally published at A Java Geek on July 16th, 2023

The post Book Review: “Designing APIs with Swagger and OpenAPI” appeared first on foojay.