So... What is an API?

August 04, 2020 (~7 Minute Read)
BASICS API API DESIGN WEB API

Introduction

The main topic of this blog is the development of Application Programming Interfaces (APIs) using mainly .NET Core. For that reason, I will start by describing what an API is. Let’s take a step back and see some of the basics. We have to start somewhere, right? 😛

You don’t need to know what an API is, only if you are a software developer. Maybe you are working in an environment with software developers and just want to understand what they are talking about (sometimes we may seem like aliens).

What is an API?

In correspondence to what a User Interface (UI) is for people (e.g. click one button), an Application Programming Interface (API) is for the software components (e.g. use an API function). It’s a way to simplify the use of complex actions, but for software. Technically, an API describes how software components should interact with each other (Carver P., 2014). It defines the calls or requests that can be made, how to make them, the data formats that should be used, the requirements and limitations, etc.

• An API lists the operations that developers can use, along with a description of what they do (API documentation).
• APIs can be used to share data between systems. This is perhaps the most common use case for APIs.
• Operating systems (such as Android, Windows, etc.) provide APIs (e.g. to open files, access memory, etc.).
• Every programming language and development platform has a built-in API that is used from developers to write programs.
• This interaction with other APIs is known as “API Integration”.

Example to Understand the Use of APIs

Let’s assume that we are developing an Android mobile application (with only one button) which takes a picture from the camera, and then, send it on our email address (Image 1). At first, this may seem like a big problem, but don’t panic! We just have to break it down into two sub-problems (divide and conquer):

Sub-Problem 1: Take a picture from the camera.

• Lucky for us, there is an API for Android OS, which provides several camera-related requests, including the “Take a Picture” request.
• To solve this problem, we will just use the “takePicture” request (as described in the related Android API documentation).
• We do not know how the API is communicating with the camera hardware and we do not care (we will not reinvent the camera).

Sub-Problem 2: Send an Email with a picture attached.

• Lucky for us, a colleague (or an internal company team) has already implemented the “sendEmail” functionality, which is available in an API (named as Email-API).
• We will just have to use (integrate) with this API by providing an email address and the captured picture file (we have already provided the email address).

Why are APIs Important?

Let us concentrate on what we can learn from the previous example and why APIs are important.

• First of all, we are very lucky :P
• APIs hide the complexity of implementations by defining a simple set of interactions that can be used instead of re-implementing them (in the previous example, the “takePicture” request was used to communicate with camera hardware).
• APIs help organize the software code by separating it into distinct sections depending on different concerns (e.g. An API for the camera interaction and another to send emails). This design principle is known as separation of concerns (SoC).
• APIs make components reusable (e.g. in the previous example, we used our colleague’s API). The same API can be both used in a mobile application and in the relative website implementation. This allows developers to focus on their actual objectives and not worry about all the complexities of every part of the system.
• APIs are the abstraction that allows keeping the business logic into a single place (e.g. in the previous simple example, we can change the email-provider at the related Email-API implementation without effecting our mobile application).
• APIs help organize and split work into multiple teams or persons (e.g. in the previous example, one team/colleague is creating the mobile application, and another team/colleague is developing the Email-API).
• Restrict Accessibility (Control Access). Each API can have different access restrictions (e.g. based on an application, user’s role, location, etc.) by using different processes or protocols (such as API Keys or OAuth 2.0 protocol).

API Accessibility

• Public APIs are intended to be used outside the organization that provides them. For public APIs, it’s important to provide different versions as evolving. This will provide stability for the clients that use that API. In addition, parts of the API can be declared as deprecated, in order to be considered as a candidate for being removed, or modified in a backward incompatible way. Therefore, allowing developers to early update deprecated parts (that will be removed or not supported in the future) of an API. Examples of public APIs are Twitter, Facebook, or Instagram.
• Private APIs intended for use exclusively internal the organization.
• Partner APIs are intended to be used only by specific partners of the organization.

Web API Types

An API that is built on top of HTTP is called Web API. There are several ways (types) to build a Web API. The following list presents some of the basic types, with a small description, just to know the basics for now (Freeman J., 2019) (Castellani S. and Dorairajan A., 2020).

• Simple Object Access Protocol (SOAP) is a protocol for accessing web services over HTTP. The Web Services Description Language (WSDL) is an XML-based interface description language that is used for describing the functionalities offered by a web service. SOAP was developed by Microsoft at the early ’00s.
• Representational State Transfer (REST) is an architectural style (not a protocol) that is based on using simple URL and by using the four different HTTP verbs (GET, POST, PUT, and DELETE) to perform actions.
• Remote Procedure Call (RPC) is a protocol for executing procedures (subroutines) on a remote system as if it were local. RPC simplifies this remote interaction by hiding its details from the programmer.

API Design

The design of an API is an important process (with many decisions) that organizes and hides the complexity of software. This is accomplished by applying the principle of information hiding, which is the process of hiding the complexity of a piece of software (that is most likely to change) into modules of functionality. This will protect other parts of the software from extensive modifications. When designing an API it is important to (Carver P., 2014) (Freeman J., 2019):

• Understand the needs of the API users and the business-cases, that this API trying to cover.
• Knowing your users and keeping their needs in mind.
• Make its users and you, happy. For that, you have to understand the challenges of the API users (e.g. limitations, specific needs) and try to help them.
• Learn about API-best-practices, but do not follow them blindly.
• Think about each decision completely, e.g. how effects the API’s usability, what additional value it will provide to the API-users.
• Design an API with consistent behaviour (e.g. consistent use of the HTTP verbs in REST, consistent Error Handling with useful information).

Summary

In this post we covered some of the basics around APIs to understand what an API is, their importance and what we have to keep in mind when designing them. It is clear that there are several principles, protocols, and ways to build an API. Thus, it is clear that is an important process, with many decisions involved. Alright, we made our first step and now we know the basics; in our next step, we will learn about the tools (.NET Core).

References

• Carver P. (2014, June 21). Your API Is Bad (And You Should Feel Bad). https://leanpub.com/yourapiisbad/read
• Castellani S. and Dorairajan A. (2020, April 29). What are the different types of APIs?. https://apifriends.com/api-creation/different-types-apis/
• Freeman J. (2019, August 8). What is an API? Application programming interfaces explained. https://www.infoworld.com/article/3269878/what-is-an-api-application-programming-interfaces-explained.html