Friends of OpenJDK Today

Book Review: “Designing APIs with Swagger and OpenAPI”

August 01, 2023

Author(s)

  • Avatar photo
    Nicolas Frankel

    Nicolas is a developer advocate with 15+ years experience consulting for many different customers, in a wide range of contexts (such as telecoms, banking, insurances, large retail and public sector). ... Learn more

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.

Facts

  • 21 chapters
  • $38.39 (eBook)

Chapters

  • Part 1: Describing APIs
    1. Introducing APIs and OpenAPI
    2. Getting set up to make API requests
    3. Our first taste of OpenAPI definitions
    4. Using Swagger Editor to write OpenAPI definitions
    5. Describing API responses
    6. Creating resources
    7. Adding authentication and authorization
    8. Preparing and hosting API documentation
  • Part 2: Design first
    1. Designing a web application
    2. Creating an API design using OpenAPI
    3. Building a change workflow around API design–first
    4. Implementing frontend code and reacting to changes
    5. Building a backend with Node.js and Swagger Codegen
    6. Integrating and releasing the web application
  • Part 3: Extending APIs
    1. Designing the next API iteration
    2. Designing schemas with composition in OpenAPI
    3. Scaling collection endpoints with filters and pagination
    4. Supporting the unhappy path: Error handling with problem+json
    5. Improving input validation with advanced JSON Schema
    6. Versioning an API and handling breaking changes
    7. 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.

Conclusion

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

Topics:

Related Articles

View All

Author(s)

  • Avatar photo
    Nicolas Frankel

    Nicolas is a developer advocate with 15+ years experience consulting for many different customers, in a wide range of contexts (such as telecoms, banking, insurances, large retail and public sector). ... Learn more

Comments (0)

Your email address will not be published. Required fields are marked *

Highlight your code snippets using [code lang="language name"] shortcode. Just insert your code between opening and closing tag: [code lang="java"] code [/code]. Or specify another language.

Save my name, email, and website in this browser for the next time I comment.

Subscribe to foojay updates:

https://foojay.io/feed/
Copied to the clipboard