Requirements & API: Definitions
Foreword
In recent years, I wrote several materials about API design and last year (2023) did a local workshops and online webinars titled “Requirements & API”. Those materials targeted for Business Analysts and Product Owners who want to learn about APIs. Why? Because I am a non-technical guy who joined an API Platform and ended up being in charge of its development as a product. So, I had to gain some tech proficiency, considering my background in business analysis.
Since I did the webinars, I have had an idea to expand and restructure the content by making it more accessible. Original blog posts lacked some storytelling consistency, and workshops/webinars were for the Russian-speaking audience. So now I am doing the final step to revise that material and extend it further continuously.
We start from scratch, uncovering what API means, what place it takes in the world of software requirements, and what components are critical to addressing. Then, we proceed to more advanced topics I want to uncover: Interface Definition Languages and API tooling.
Here, you can check the entire plan. I will publish each chapter on Medium alongside my blog, so stay tuned!
What is API?
API stands for the “Application Programmable Interface,” and this definition is self-explanatory and unclear at the same time. It is a vast term, and different people with different roles have different understandings of what it is.
Let’s go old-fashioned and ask Wikipedia:
“An application programming interface (API) is a way for two or more computer programs to communicate with each other. It is a type of software interface, offering a service to other pieces of software.”
That gives more clarity but might sound ambiguous. I would focus your attention on “ offering service” as that is crucial in our further conversation.
There is another excellent definition from the “ The API Book” by Sergey Konstantinov:
An API is an obligation. A formal obligation to connect different programmable contexts.
The author draws an analogy with a Roman Aqueduct dated to the 1st century AD as it:
- interconnects two areas
- flows water (analogy to data)
- keeps backward compatibility for almost 2000 years
- provided an additional infrastructure to support water supply from both ends.
I suggest thinking about API as a distribution channel. It is like a User Interface (UI): not directly for end-users, but for developers to build their solutions on top of API for their end-users.
API Lifecycle and Actors
As with everything in that universe, API has its lifecycle and different people allocated to its various phases. We distinguish a Producer who develops API and is responsible for its further support and a Consumer who utilizes that API for their purposes. However, that is not a one-sided charity. Producers receive something in return, whether it is money or data.
Under Producers and Consumers, we don’t mean only developers, as many other roles are involved: Business Analysts, Software Architects, Quality Assurance Engineers, Product Owners, Delivery Managers, etc.
The lifecycle differs whether you are on the Producer’s or Consumer’s side. For the Producer, there are the following stages:
- Definition: defining what API should do
- Design: answering on how API should do, designing its component
- Delivery: developing and publishing API into the outer world
- Operation: running and supporting API
- Deprecation: announcing plans to finish support, preparing migration strategy, removing API
The Consumer’s lifecycle starts a bit later than the Producer’s:
- Discovery: identify API that provides value for your business
- Integration: enable API into your service
- Delivery: utilize API for your purpose
- Migration/Deprecation: migrating to a new API or another Producer; closing the feature/services that utilized API
The beauty of API is that Discovery and Integration do not require an API to be up and running somewhere in the Cloud. In particular cases, the Consumer may ask to share an API contract and/or provide a mock API so they could integrate beforehand. Consumers will not get a working API until the Producer Delivery happens, but they can do their part of the work and not be blocked from proceeding. We discuss that topic in the following chapters.
The integration is an important part: it is not free as Consumers apply some effort to integrate with API and embed it into their solution. Producers can alter APIs that might hurt Consumers unexpectedly. That is where the concept of Backward Compatibility applies as a temporary (nothing lasts forever) obligation that the Producer will take care of the smooth operation. We will discuss that concept further as well.
There is another Actor that is usually hidden from the public eye: the API Platform. Producers need proper tooling to expose and manage their APIs. The task might be easy if we talk about a dozen API operations. But there can be hundreds if not thousands of operations of different types, formats, protocols, etc. Keeping quality standards and consistency across the APIs, providing means to quicken the development, and ensuring required management policies are the challenges to be handled by the API Platform. We cover that topic separately.
The Value Chain
From the API Platform perspective, you are too far away from end-users who get some value from indirectly using your API. Your immediate users are the producers who build APIs using your platform. They have specific needs: quick-time-to-market, reliability, monitoring, support of different protocols, etc. But basically, they need to be able to design & deploy quickly and straightforwardly.
However, the platform’s role is to imply specific rules and limitations. It is not responsible for the outcome. Is it on the API developer’s shoulders? However, it could provide some quality gateway and not allow API to be published until it meets the required criteria.
Taking into account all those policy and technical limitations, API developers are building APIs. And it is essential to mention that API does not equal a feature or a piece of system functionality. API is a way to access and utilize it programmatically. There can be multiple ways to access one particular piece, but they are designed for different scenarios. Yes, again, that is a distribution channel.
So API developers need to extract a piece value from the system and, with API Platform, make it available.
On the Consumer side, a so-called Business Owner decides whether an API under consideration will satisfy business needs. In another case, a Business Owner requests an API from Producers. That business owner might be anyone, a product owner, another team member, or some stakeholder from your business clients. There might be different approaches in handling internal and external owners, but the idea is the same: they will only pick and utilize an API if it does some job for them.
The integration happens, and the value, in a significantly transformed way compared to the beginning, finally passes to end-users. However, if we consider B2B2B, the value chain might be longer. So, the API platform and developer folks from the producer side are distant from end-users. Should they even care about them? They should.
API Categorization
Multiple categories can be applied there:
- by accessibility: public, partner, internal
- by complexity: basic (CRUD operations), composite (converging several Models)
- by interaction: synchronous (client waiting for a response), asynchronous (client doesn’t wait; it will get a response later, if any)
- by monetization: paid, free
But the most controversial is the technical one. Let’s consider REST (REpresentational State Transfer), SOAP (Simple Object Access Protocol), RPC (Remote Procedural Call), and GraphQL. Besides they are all API-related, there are also different levels of abstraction:
- REST is an architectural style
- SOAP is a messaging protocol specification
- RPC is a request-response protocol
- GraphQL is a query language (that is what QL stands for).
REST is the most problematic topic because, as an architectural style, it has a lot of representations. I like an analogy with classicism as an architectural style in construction. As a mere mortal, you can know some common traits of that style. But you are unlikely to distinguish it from neo-classicism.
REST architecture styles principles:
The client and the server do not know how each of them is implemented
Sessions are stored on the client (the “stateless” constraint)
Data must be marked as cacheable or non-cacheable
Interaction interfaces between system components must be uniform
Network-based systems are layered, meaning every server may just be a proxy to another server
The functionality of the client might be enhanced by the server providing code on demand.
And that’s it. Not much, right? I suggest reading other sources if you want to dive into the topic. General terms described in the REST principles can be interpreted and implemented in many ways. Term REST API has caused holy wars in the tech community for 20 years. So, there is a notion of RESTful API that loosely follows some REST principles.
Instead, let’s focus on HTTP (HyperText Transfer Protocol) because it is the foundation of modern API. REST author Roy Fielding is also a co-author of HTTP. So they are literally tight together. Also, GraphQL is served over HTTP, HTTP is the default protocol for SOAP, and RPC uses HTTP as the underlying protocol.
So, we start with what is called HTTP API and keep exploring that concept in the following chapters.
Originally published at https://ilyazakharau.com.
