Skip to content

API

New Chapter of Requirements & API - Interface Definition Languages (IDL)

A new chapter in the Requirements & API series continues uncovering API design specifics. This time, we look closer into IDLs (Interface Definition Languages).

I examine OpenAPI as an industry standard, Microsoft-powered rival TypeSpec, and an underdog JSight. They have a similar purpose but achieve that in very different ways.

We are approaching the end of the journey. In 2025, one more article will describe API workflows.

For now, that's it for 2024. Of course, there will be an overview reflecting on the past year and sharing some plans for the upcoming one.

Stay tuned!

Previous chapters:

New Chapter of Requirements & API - Design

A new chapter in the Requirements & API series focuses on structuring each layer to design an API. This time, it is more practice-oriented, with examples of an HTTP API call and its OpenAPI definition.

I am in the hallway through that series. Almost a year ago, I did two webinars on the topic. Those articles help look deeper into the topic, which is better done in writing.

I originally planned to retell my material from offline and online events. However, reality is different, so there are many deviations and extensions.

So, two more chapters will come, and the topic will be closed. I have been writing and talking about APIs since 2022. I continue working as a product manager on the API Platform, and the articles about APIs get more attention from the audience than anything else.

So enjoy reading on Medium (friend link)

Or here: Design

Previous chapters:

A new part of Requirements & API - Analysis is available!

Last month, I started summarizing all my API-related posts, workshops, and webinars into extended and structured reading. That is usually a part of the Essays section, where you can find my recent Replacing Legacy series.

Reflecting on my past materials about API, I realized they were disconnected and lacked a logical narrative. However, I am proud to share that I am starting anew, from simple concepts to in-depth reviews of various Interface Definition Languages, showing significant improvement in my approach.

The new chapter, "Analysis," focuses on business analysis and aspects of requirements engineering. That was tough to write and edit, cutting pieces that did not fit and made text difficult to comprehend. Hopefully, I will get a satisfactory result.

Previous chapters:

  • Definitions, the best place to start the journey.
  • Glossary that I keep up-to-date with terms and abbreviations.
  • The index page is where you can find a plan for future topics.

At the same time, I am publishing it on my Medium to reach a broader audience. I would appreciate your support there.

Next time, we discuss HTTP protocol and API structure using OpenAPI as a reference.

Stay tuned and take care,

Ilya

  • in API
  • 5 min read

My Learning Path Toward API

Before 2020, I dealt with API as a Consumer with intergration purposes, using only such tools as Swagger UI, Postman, and Insomnia. Since 2020, I have changed my side. And not as an API Producer but one who gives the Producers tools to build APIs. It's about the API Platform.

So, back then, I started my journey to learn more about API and Platform design. And it is far from being over. I can say that I know more than an average person with business analysis background about that topic. But I can't call myself an expert anyway.

During the recent webinars, there was a question about what I can suggest to learn about APIs. With this article, I address that question but in a different form. Instead of a reading list, I decompose the last three years of my career and describe what I did and keep doing to learn about APIs being an API Platform Product Manager.

  • in Media, API
  • 3 min read

Summary of the "Requirements & API" webinars for IIBA Belarus

Overview

Following a theoretical Part 1, I was glad to talk about more practical API-related things and ways they can be designed.

While preparing for the webinar, I expanded my knowledge of the FastAPI Python framework to design mocks. Some of them were not only displaying docs in Swagger UI but also worked kind of. My overall purpose was not only to talk about APIs from the Business Analysis perspective but to show them.

  • in API
  • 6 min read

Breaking changes & Backward compatibility

Breaking changes everywhere

I learned what backward compatibility means regarding software engineering when I started working on microservices. When you are responsible for services widely used by other teams inside and partners outside, you most likely become paranoid about maintaining backward compatibility of your API as much as possible. Especially when it is a highly volatile environment with rapidly growing functionality and direction changes on the fly.

At some point, I invented the term "backward awkwardability" - an awkward feeling while telling consumers that there are breaking changes in a new release, so they have to migrate. If your team does it frequently, they will say something like, "C'mon guys, you introduced breaking changes just a few iterations before! What's going on?"

Let's talk about backward compatibility and how to deal with the breaking changes in terms of API.

  • in API
  • 5 min read

Non-functional Requirements and API

Slides from API Workshop about Non-functional requirements

Previously we discussed the notion of requirements for APIs. Now let's talk specifically about their quality attributes. Or how we can refer to them: non-functional requirements.

When we use the term "non-functional requirements," we imply that there should be "functional requirements" as well. What is a functional requirement for an API endpoint? Return a response based on the provided input data. It sounds oversimplified, but this is how it is.

In detaching API from the functionality, meaning we have a variety of APIs for different consumers, I like an association with a "door." Despite any context, the primary function of a door is to change its state from closed to open and vice versa. The door can be built from different materials, and it can be opened by various means. The opened door can lead to different locations. But its primary function remains the same. We are not considering it as a weapon, even if you hit someone by a door (accidentally, I believe).

However, the quality of that door matters, and the same we apply to API. There are dozens of non-functional characteristics, so we only look at major ones.

  • in API
  • 7 min read

Definition of API Requirements

Cover

Requirements definition for APIs is not a standard part of the Business Analysis activities in software development. Usually, API design was a single responsibility of a system architect or a developer, considering implementation subject matter experts.

During my BA career, I had to deal with API-specific requirements. I realized that the API layer has stakeholders (aka consumers) who have their needs related to APIs provided by a system-of-interest. And those needs should be analyzed and translated into requirements.

The goal of this essay is to give an introduction to the definition of API requirements for my fellow Business Analysts, Product Owner, and Product Managers. I will not discuss technical details and cover API types (REST, RPC, GraphQL, etc.). There are a lot of experts who have done that and did a great job.

I will focus on general things, looking at API from the requirements perspective in general. Also, I have mostly worked with RESTful API, which impacts my view on some things.

  • in API
  • 8 min read

API Design Tooling

This article is a part of the API Design series, where I will review several API design tools and summarize my experiences. There are the following criteria I use in selecting and evaluating the tools:

  • it is free: either open source or a free plan of a paid product
  • out-of-the-box functionality is considered only: no plugins
  • both web and desktop products are considered
  • it allows designing REST API definition in OpenAPI 3.x with JSON/YAML (low-code), UI means (no-code), or a combination of both
  • code generation functionality is not required as there are several 3rd party libraries to do that

I am not promoting, just expressing my honest opinion. But I might have my favorites. Also, I will describe these tools at the moment of December 2022.

  • in API
  • 6 min read

API Design-First

This article is a part of the API Design series, where I will uncover API design concepts for my non-technical peers. You don't need to be a developer or an architect to participate to design or even build an API, but there is something you should learn to succeed.

So we start with API design-first, which takes the opportunity to democratize the API development process.