5. APIs highlighted from multiple angles
What are APIs and why are organizations API-Driven?
Aleksandra is busy with her webshop for cakes and pies. To share new cakes, she quickly created an Instagram account. But there are also many other channels, such as LinkedIn, X, Facebook and Pinterest. If she has to manually put all the posts in all these channels, little time is left for baking. Easier is to create one post on her own website and then share it through the APIs of the various social media channels.
Almost all social media, such as Facebook and X offer an API. You can call such API to post a tweet, for example. Of course you can just log on to the Facebook website and leave a tweet: “super delicious cakes,” but if you want to automate this, it’s better to use their API.
Almost all organizations today make their functionality available through APIs. Previously only big tech companies like X did this, today your local baker does this as well. So it is ubiquitous, but really a different way of doing integration. That’s why we cover this topic in a separate chapter.
What is an API?
A programmer soon writes a script to automate his work. The lines of code in such a script are simply executed by a computer from top to bottom. To perform some actions in multiple places, the programmer creates a generic function. For example, logging all kinds of information.
It soon becomes apparent that this function is useful in other scripts as well. Finally, he collects the various generic functions in a library that can be called from all kinds of scripts. Basically, behind every API is a library of generic functions.
An API (Application Programming Interface) is:
A set of clearly defined methods of communication between various software components. A good API makes it easier to develop a computer program all the building blocks, which are then put together by the programmer. (Wikipedia)
An API goes one step further than a library. First, an API makes a clear distinction between publicly available functions and internal functions. Second, an API abstracts the implementation of these functions by superimposing an interface layer on top of them. This focuses on the clients calling these functions.
An API is the showcase of all the functions an application offers. Just like a showcase with all the cakes for sale.
Since the 1970s, APIs have been written in a variety of programming languages, such as C, for example. In Java, even creating an API is part of the language itself. Creating a list of functions is called “interface” there.
The structure of a program using an API is as follows:
Web Services
There is a strong drawback to programming language APIs. The programs calling the APIs must be written in the same language. For example, the broker ActiveMQ uses the Java API “JMS.” Therefore, the programs calling this API must be written in Java.
One way out of this problem is to make the functions available over the Internet. This is known as Web services. Calling such functions are via HTTP requests. The first Web services used XML. They defined a Web service with SOAP (Simple Object Access Protocol). Today, REST Web services, also known as REST APIs, are the standard.
REST API’s
REST is an architectural style for sending, deleting or retrieving data to an API via HTTP requests. This architectural style was developed in 2000 by Roy Fielding for his dissertation. In his research, Roy describes how software can communicate with other software.
The acronym REST stands for REpresentational State Transfer. But this abbreviation doesn’t get us much further in understanding what it is. Better to consider exactly what software components are communicating with each other. This is a client (for example, software on the phone, laptop or server) with a Web server (The REST Web Service):
HTTP Request
An HTTP Request consists of the following components:
- Action
The type of action to be performed. The most common actions are GET, POST, PUT or DELETE. The HTTP response message contains the response from the API.
2. Endpoint
An endpoint usually takes the form of an Internet address:
3. Headers and Body (optional).
The request that makes the request can also contain headers and an optional body.
Resources
On the Web server, behind the endpoint lays a resource. Resources are the core data your application works with, such as an invoice or an article. Multiple resources are again called a collection. A collection of REST endpoints and collections is the REST API.
Pros and cons of REST
Pros
One of the main advantages of REST APIs is that they use Internet standards. This makes them technology-independent. Independent not only of infrastructure, but also of programming languages. A call can be made from a .Net application on a REST API with a Java application behind it. Because the URI is used over the Internet, hardware resources can be placed and scaled anywhere.
REST is also popular because it contains only a limited number of actions in basic terms, namely GET, POST, PUT and DELETE. These are quick to build in and connect well to the database layer.
Multiple applications can also be connected to the same API. For example, these can request an article. For example, a call is:
GET http://example.nl/api/artikel?type=basisThis call returns the basic information of an item. Another application can make a more extensive request:
GET http://example.nl/api/artikel?type=allCons
Like creating a database or program, setting up an API requires a lot of work and tuning. And as with the integration techniques mentioned in the previous chapter, setting it up incorrectly poses a problem later on. The downside is even greater because it involves multiple programming options. It is not a one-to-one connection:
REST does not help you organize things. It forces you to use API supported by server-side library you are using. You can organize your application the same way (or better) when you are using non-REST approach. It all depends on how well you organize and document your application. REST will not magically make your application better.
REST makes use of HTTP. This protocol is also known for not providing clear definitions for actions and error codes. For example, there are no rules indicating when to use POST and when to use PUT. Beyond GET, POST, PUT and DELETE, there are other actions, such as PATCH and TRACE, but these are often not implemented and therefore you cannot just use them.
Some of the same ambiguity applies to HTPP Response codes:
Consider, for example, when we might use the 200 OK response code. Should we use it to indicate the successful update of a record, or should we use 201 Created? It seems we really should use a code like 250 Updated but that code doesn’t exist. And can anyone out there explain to me what 417 Expectation failed really means?
Because there is not a very strict standard, setting up and debugging a REST service takes a lot of time. One standard for REST that is becoming more widely used is OData (Open Data Protocol). Using OData eliminates the need for agreements on HTTP methods, URL conventions, media formats used and query options, among other things.
API as a product
An API is certainly not just a technical component. As indicated, the advantage is more in that it uses Internet standards and not necessarily in other technical benefits. The biggest advantage, however, lies on the business side.
APIs are for an application what the store window is for a store. Think of it as a list of all the cakes the bakery can make. A customer walks by the store and sees all kinds of cakes in the window. These cakes (and they don’t even have to be real) should look attractive and be presented in an orderly fashion.
Someone using an API is therefore usually referred to as a “consumer.” For these reasons, it is common to design an API as a product for a consumer. Multiple API endpoints should be consistent and clear to those who will use them. The user of an API is generally a developer. An API gives a developer insight into what features are available to an application.
Developer portal
Suppose you want to throw a big party for which Aleksandra is making some cakes. Traditionally, you would call her and arrange with her which cakes you need. Nowadays, however, this can be done entirely digitally through the website (user interface) or an API (data interface).
Even with traditional integrations, project managers, architects and developers often met physically for coordination. With APIs, everything goes digital. A developer publishes his API in the so-called developer portal. And other developer logs into this portal and examines the various APIs (the showcase). Then he adjusts his own program (the client) accordingly.
An API is created so that other developers can use it. The idea is that developers can explore and use an API themselves. This showcase is also called a developer portal or developer portal. But how do you create such a portal?
A developer portal has clear specifications so that they can be displayed. Well-known specifications are:
Using these specifications, the API can be designed and then documentation can be generated from it. Finally, this documentation is made available in the “Developer Portal.”
API Gateway
APIs are in the developer portal (the showcase). However, it is not intended that anyone can just access data from it. Just like you can’t just grab something from the showcase, with API you will have to get access first, to share the data in a secure way.
The software that creates and manages the storefronts is the API Management Platform. The core component of this platform is the API Gateway. We encountered this one earlier in the “Technical Integration” section. An API gateway resides between clients and services. Technically, it acts as a reverse proxy, for routing requests from clients to services.
An API Gateway is configured in an API Manager. Here you can determine, for example: who gets access to the API? what happens if something goes wrong? and how do you arrange load balancing? Logging, version control and usage statistics are also maintained through the API Gateway in the API Manager.
Why API Management?
There are multiple ways to build an API layer. If there are only a few APIs, then they can just call each other directly. If there are multiple APIs, then a piece of management is necessary. This management, the API Management, takes care of all matters surrounding APIs. Think of publication, security and management:
API management is the process of creating and publishing APIs, enforcing their usage policies, controlling access, nurturing the subscriber community, and collecting and analyzing usage statistics. (Wikipedia)
Virtually all major software vendors, such as Microsoft, Google and IBM, offer an API Management product. Well-known open source players in this area are Mule, 3Scale, WS02, TYK and Kong.
API Management ensures that you maintain control in managing your APIs. From a technical and management standpoint, it’s clear why you need API Management. After all, you need to be able to scale your environment, but also keep visibility when something goes wrong.
The main components of API Management are:
- API Designer
- API Gateway
- API Tester
- API Manager
- API Developer Portal
In the development process of APIs, the various components are used.
API Economy
Suppose a factory makes all kinds of raw materials and supplies for bakeries. This factory may be looking for all kinds of customers. Those buyers naturally want to know what type of ingredients and supplies the factory sells and what they cost. Buyers might be bakeries, but they might also be wholesalers who want to display the product information on their Web sites.
Now the factory can go and create an integrations for each buyer, but it can also make one API available. All the different buyers can thus retrieve the information they want and integrate it into their own systems. They can also use the API to place orders.
So the beauty is that there is only one API for all buyers. They can use it without the intervention of the factory. In fact, the factory does not need to know anything at all about the buyer (user of the API). For example, one suddenly gets orders from regions where the factory does not operate. So the data from the factory can be used in very different contexts, even in contexts that were not foreseen beforehand by the provider of the API.
The business model and best practices around the use of APIs are also called “API Economy.” Thus, for the factory, the API itself is also a product. By viewing APIs as products, data exchange works differently than traditional integrations. Integrations are supply-driven components, while APIs are more demand-driven components.
