Understanding APIs

The term integration is still an abstract concept without seeing some examples of technology that can implement it; but don’t worry, we’ll get there. Let’s now switch gears and dive into another popular term we hear a lot nowadays: API.

If you’re a visual person, we encourage you to watch this video, https://youtu.be/s7wmiS2mSXY, from MuleSoft to see an animation with a restaurant analogy that is widely used to explain APIs. This step is optional, but it might help you to understand this concept better. We will walk through the restaurant analogy in the following section.

Reviewing the restaurant analogy

When you go to a restaurant, after you sit down and get yourself comfortable, a server will come to ask for your order. You order your dish, the server writes it down, and then they proceed to communicate the order to the kitchen. The kitchen staff works their magic to cook your meal, and then let the server know when the meal is ready. The server picks up the dish and takes it to your table for you to enjoy.

Now, let’s break this down into smaller pieces:

1. You order your food.
2. The server writes down your order and sends it to the kitchen staff.
3. The kitchen staff prepares the order and gives it to the server.
4. The server picks up the order and brings it to you.
5. You receive your food.

We can look at this process as if it were API calls:

1. You call the Server API, requesting some food.
2. The Server API forwards your order to the Kitchen API, requesting your food.
3. The Kitchen API processes this information and responds with your food.
4. The Server API takes the food and responds to your order with the food.
5. You receive the food and confirm it is correct.

Figure 1.2 – API calls in restaurant analogy

The important things to understand from this analogy are as follows:

• You don’t know what the server wrote down in their notebook that was sent to the kitchen
• You don’t know all the ingredients that were put into your food or the exact process that the kitchen staff followed to prepare the order
• You don’t know what the kitchen staff told the server to let them know your order was ready

All that you know is that you ordered something and you received what you had ordered. APIs are a lot like that.

Fun fact

In a restaurant, you are the client and the person who brings your food is the server. Guess what it is called in the API world? In API lingo, the application that calls an API is called the client application, and the application or API that responds is called the server application.

Let’s now look into a real-life API to understand it better.

Exploring an API example

There are thousands of APIs that you can use in the real world. An example that we can use to demonstrate is the Twitter API. Twitter is a social network that is popular because of the maximum number of characters allowed in a single tweet. As of the time of writing, you can only post 280 characters at a time, which makes it ideal for short thoughts or quick updates about different topics. Once you have a Twitter profile and start following other accounts, you will be able to see the tweets from those accounts on your home page, or timeline.

If you go to the Twitter API documentation (developer.twitter.com/docs/twitter-api), you will be able to find all the different requests and responses that you can use to communicate with the API (the menu from the restaurant analogy, if you want to look at it that way).

Figure 1.3 – Twitter API documentation site

You can find the technical details to call the API and receive a list of your own tweets, for example; or you can post a new tweet using this API. This is useful if you want to communicate with Twitter using a backend application, if you’re developing your own app that can talk to Twitter, or if you want to integrate Twitter with other apps. For example, you can use social media tools (such as Hootsuite or Later) to schedule posts on your social networks. You give them the information you want to post and they take this information (or order) to the backend systems, which will make this possible (like the kitchen staff).

Any integration you create using the Twitter API can be written in any language or technology you decide. It doesn’t have to be compliant with how Twitter developed their APIs. That is the beautiful thing about the APIs. They offer their documentation so you know what’s available from them (like the menu from a restaurant) and you can make the appropriate requests to receive the data you need. The only thing you need to do is send the data in a format that the API is expecting, but any processing before or after the API request can be handled however you see fit.

To put it in more technical terms: you don’t know exactly what programming language the Twitter API is built in or what kind of data type it uses internally to process the information, but you do know the type of data it accepts and the type of data it returns. This is all you need to know to communicate with it.

Analyzing API components

Now that we have a better idea of what APIs are, let’s start looking into some components to define them. We won’t get into the technical details just yet, but it is good for you to start familiarizing yourself with this terminology.

Implementation

The implementation is the body of the API, that is, the code you choose to build the API with, the part that does the processing of the request and the response. We will use this term interchangeably with API throughout the book.

Request

Whatever is sent to the API is called a request. This includes different kinds of information that will tell the API what needs to be done with the data that is received. In the restaurant analogy, this can be, for example, a hamburger with no pickles, in a combo, with a large soda, and some fries on the side. 

Response

Whatever is received back from the API is called a response. This includes information to describe what happened in the processing of the requestor, for example, whether the request was successful or not or whether there was a problem with the request. In the restaurant analogy, this can either be the food you ordered (a successful response), the server telling you that the dish is no longer available but you can still order something else (a failed response with a workaround), or the server telling you that they’re closed for the day (a failed response with no workaround).

API specification

This specification serves as a rule, standard, or contract – however you want to look at it – to tell the client application (the application that calls the API or sends a request to the API) what kind of information it needs to send to the API in order to be accepted and processed as needed. For example, if the API specification says the API only accepts JSON requests and the client application sends an XML request instead, then an error will be returned stating that this data type is not accepted by the API. This is also a contract in the sense that it lists what the API may or will return to the client application, for example, a JSON object containing the id, firstName, and lastName fields.

Listing the benefits of using APIs

We still haven’t talked about the technical aspect of an API, but we’ve seen some examples and an analogy to help us get a better idea of this concept. Let’s list some of the benefits of using APIs:

• Loosely coupled: We touched on this subject briefly, back in our explanation of integration technologies. When you have a lot of systems that you need to integrate, you can create an application network with loosely coupled APIs that communicate with each other. This is a better alternative to having a huge, tightly coupled system that can’t let any more functionality in or out without having a dependency problem.
• Governance: With the APIs approach, you have a better chance of being able to govern your network. You can create API gateways, policies, and any sort of security to ensure that no unwanted intruder can get to your APIs. This can be a challenge with legacy systems sometimes because you need to create personalized code or external solutions may not be available for your system.
• Discoverability: APIs, as opposed to legacy systems, have a best practice of including documentation to use them. Since these are supposed to be open to the public, or easily discoverable, organizations also want their users (developers) to be able to find them and start using their APIs. Because of this, they try to generate better documentation with examples, use cases, descriptions, and even sample code.
• Easier maintenance: In hand with the loosely coupled and discoverability benefits, the developers that end up maintaining these APIs have a better understanding of their code. Because APIs are supposed to cover a small, specific use case for the developers, it is also easier for them to understand the code. Legacy systems, however, end up being a headache because of their millions of code lines and dependencies.
• Efficiency: From a project management perspective, we can also take this point into account. Because APIs have less code and their functionality is so specific, the time to deliver new features can be shortened compared to other architecture types or legacy systems.
• Reusability: As we mentioned earlier, we want to create an application network that connects all of our APIs to bring together a system that covers our needs. Since APIs are so small and functionality-specific, they are created with reusability in mind. The output response depends on the input request it receives. This is helpful to reuse specific functionality that is consumed by several services or systems and there’s no need to create custom code since they’re loosely coupled.