Architecture of API-Management In An API-First World — Part I
A detailed tour of the world of API Management and systems based on the API-First methodology.
As I am writing this post, it is turning to be a very long article, explaining many details and concepts. I’ve decided to break it down to at least 3 separate posts:
Chapter 1: Introduction and explanation of the different terms and concepts used in these posts.
Chapter 2: The 4 (some say 5) roles of an API Management system
Chapter 3: Thoughts about designing API-First systems in large organizations.
First, the statement:
While the thoughts here are based on conversations and experience with real customers and systems, these are my theories, and do not reflect any project or job that I have been involved in.
Introduction:
Unless you’re absolutely new to the tech world (or to the contrary — you haven’t changed your coding style in 20 years), you probably know that the way code is designed today is by running small micro-services, and providing (mostly RESTful) APIs for features and solution developed. Gone are the days with one big system with one entry point serving all customers as one with a single client-side application.
Many actors accessing the system from many different access routes requires organizations to place a gatekeeper between services and the world to secure, route, monitor, and (where relevant) monetize on the traffic flowing externally (to the world) as well as internally (between different applications in the same organization).
This series of posts is an attempt to give basic guidelines of how these systems should work, and what principals should be leading us when we design our API Management solution in an API-First world.
Terminology:
Main players: Throughout this article (and those to follow) I will be referring to the different players in the organization who interact with an API Management system. The names and terms described here are taken from Amancio Bouza’s Medium article, and it is recommended to visit there for more details:
- API Provider: what was once known as “server side”, and then “the backend”. When a feature or specific solution is built, it is exposed to those who want to access/activate/consume/etc. it as an API call. The API Provider receives a Request, and returns a Response (always).
- API Consumer: The one calling the API that is provided by the API Provider is the API consumer (a.k.a “the client”, or “the front-end”). It is highly recommended for the Provider and Consumer to agree on a shared contract called OpenAPI document (more on that soon).
- API Customer: The customer is the entity providing a business solution by interacting between the end-user and the API Provider, acting as an API Consumer. An API Customer is a consumer of several APIs, using credentials provided for a single specific customer (A customer builds an application which consumes many services).
- End-User: The purpose of building the system in the first place, was to provide some value to an external entity. Usually we think about a human holding a mobile device or using a computer, but this is clearly not the only case. We build systems with API architecture also for machine-to-machine (IoT) communication. (would we not use RPC in those cases? I hope to get to write about that in the future).
API Management: API-Management is a system that stands between API-Consumers and the API-Providers, and is a layer that handles everything that is not the core of the Request/Response content and parameters. The Provider receives various input arguments, and returns a response according to the OpenAPI contract that has been defined (OpenAPI is not mandatory, but a pretty basic requirement if we want a healthy system). All the metadata, such as identification and authorization, load balancing, logging, etc, should not be the concern of the serving layer, and we would like to assign these roles to a different entity. hence API Management.
API-First: There’s a famous story that back in 2002, that Jeff Bazos sent an email to all developers that from that day on, every solution written will be exposed and consumed as a(n API) service. This change of making each solution an atomic endpoint that can be accessed by anyone any time, opened up possibilities that were unthinkable before. This mindset is what lead to what became later the AWS, and pioneered the cloud technology, making everything, including computing infrastructure — a service that can be called by anyone, from anywhere.
The evolution of this mindset is to make the API the anchor to a given solution. We define what we want to build, set the API for it, so that the provider and consumer know what to send and receive to/from each-other, and once that’s covered, move to writing the internal business-logic.
API-First is the brother of API-Economy, where we view the API endpoint as the source of value, hence source of income. There’s a lot to write about that, but a quick and simple example of that revolution is Twilio.
OpenAPI: Was once known (and unfortunately is still referred to) as “Swagger” — this is the contract that defines the objects and methods that will be handled between the API Provider and API Consumer. The contract will state the server(s) where the solution is served, a list of endpoint paths, each of which is a pair of request and response. The request and response contain the expected structure that will be communicated, where on the request/response will it be found (is it a header? part of the path? query string? etc), what is mandatory and what not, expected format, example value, and more. The OpenAPI structure encourages the re-use of objects and schemas, with a rich set of reference capabilities. OpenAPI contracts also state the security rules and roles expected to be enforced for each endpoint. Every layer of the OpenAPI contract has a summary and description attribute as well, so that both sides of the contract can understand what is expected in any given interaction. All this — in a single JSON/YAML file that is easily read, and can easily be enforced on the API Management layer, keeping insufficient requests/responses away from the providers and consumers, saving expensive computing resources.
I also believe a good OpenAPI document can be the basis of a development contract between real-world customers and developers, anchoring what should be built, and what is the expected input/output for each request. A single readable web page, replacing dozens of Word pages in multiple versions, where you’re never sure which version you should be working on…
This is the end of the introduction. If you’re procrastinating — GET BACK TO WORK. Otherwise — You are more than welcome to continue to the next chapter. Feedback of (almost) all types is always welcome.
