Skip to content

API Design Series Overview

In 2022 I started exploring the API design-first approach and dedicated to this topic a series of articles on Linkedin (1, 2, 3, 4). I have revised the entire material and published the enhanced version on my blog.

The enhanced version is more structured and has better language. Also, I rewrote some sections for more clarity. If you have already read those articles on LinkedIn, I encourage you to revisit them here.

I decided to choose a more common term, API design, to entitle the series. Because of that, the series with a few articles might get more content in the future.

It will be helpful for those Business Analysts, Product Owners, and Product Managers who want to learn more about API design concepts, tools, and find useful materials to continue the study.

Part 1. Definition of API Requirements

An introduction to the API world, where we cover the following:

  • why do we need to write requirements for API
  • basic API terms you need to know
  • what is API definition, API contract, and request logic

Part 2. Non-functional Requirements and API

Here we talk about quality attributes for API (aka non-functional requirements):

  • security
  • reliability
  • performance
  • usability
  • maintainability
  • compliance

Part 3. API Design-First

In this article, we explore the following:

  • why API definition is involved
  • what API design-first means
  • what are the benefits
  • what are the disadvantages
  • where should you go to learn to design API

Part 4. API Design Tooling

In this article, we review six low-code and no-code tools to design your API quickly and for free:

  • Swagger Editor
  • Postman
  • Insomnia
  • Stoplight
  • Apicurio
  • Apibldr

Part 5. Backward Compatibility

Here we learn how to avoid breaking changes, if possible