What is an API? What makes it good or bad?
The speed at which we produce and exchange information has increased significantly within the past 200 years. It started with electromagnetic telegraphs in 1833, but it went wild as soon as the first email was sent in 1971.
It was a revolution. Suddenly people around the globe could exchange written information.
At the same time, we started to automate more and more tasks. ATMs started to replace bank tellers in 1972; public transportation replaced a good chunk of individual traffic, and bigger agricultural machines led to more efficiency.
The more things and services received a digital representation, the more we could automate. Connecting those services became increasingly important: You want to be able to send emails for recruiting and have those within a recruiting portal. Once you’ve made an appointment, the date should be in the recruiter’s calendar.
Connecting services means that one service needs to provide information and another service needs to consume it. And the consumer has to be able to “speak the same language” as the provider. This could be a file format like
.ical for calendar events. Or it could be another interface than a file. An interface developers can use to program their own stuff. An Application Programming Interface, or API.
Lots of people write software. Sometimes their program can do everything on their own, but in many cases, developers (also known as programmers) use other people’s work as building blocks. That happens in various ways: Copying the code of others directly into your own project is called “vendoring.” If you install the project on your machine, it’s typically called “using a library/framework.” And then there are services.
APIs are first and foremost interfaces. Like a remote control is an interface to a TV.
Interfaces are at the border of two systems. They allow the two systems to interact.
An API is an application programming interface.
An API is an interface between two programs.
You can define APIs in many different ways — the same way you can with remote controls. But just like some TVs don’t accept some remote controls, not every program accepts every API. Developers have to work on adding support for a specific API.
A very common set of APIs are so-called REST-APIs. They work on top of the HTTP protocol. That uses the request-response principle, similar to people using their browser:
- Request: The program sends a request to an endpoint (the URL). For example
https://example.com/api/books. That request might contain more information in two forms: the header and the payload. The header could be authentication information — anything that lets the receiving server know that you are allowed to see what you request. The payload specifies exactly what you want, e.g.,
series=Lord of the Rings.
- Response: The response can be anything. It also contains a status code, a header, and a body. The header might tell you that the body is compressed or that it was cached.
For this article, I mean “REST-APIs” when I speak about APIs. There are other APIs, but REST is the most popular API style today.
REST APIs are commonly documented using the OpenAPI specification. OpenAPI documentation is stored in a text file in the YAML format. It looks like this:
You can see that the domain (example.com) is not specified, but the rest of the URL
/store/order is there. It specifies the HTTP method “post.”
HTTPmethod is just another part of the protocol. There is
GETfor retrieving stuff,
POSTfor creating stuff,
PUTfor modifying stuff, and
DELETEto remove stuff.
The document defines that the request body has to be in JSON format and follow the
Order schema. That one is specified later in the OpenAPI document.
Furthermore, the OpenAPI document specifies which responses you might get when sending such a request: A status of
200 for a successful order and a status of
400 for an invalid order.
There a lots of HTTP status codes. All of them have 3 digits and the important part is the first digit: 2xx is a success message, 4xx is an error with the request, 5xx is an error with the server. You will not see 1xx and 3xx so often. Details matter, but only to the developers.
There are two tools to make the OpenAPI specification file readable: ReDoc and Swagger.
Swagger is a well-known and widespread solution. They have started the development of the OpenAPI specs. That is the reason why we use the terms Swagger and OpenAPI sometimes synonymously, although they are conceptually very different
Swagger is a tool that uses OpenAPI specifications to generate documentation for REST APIs.
Swagger documentation looks like this:
ReDoc is another way to show the documentation:
Typically the hardest part about a new API is getting started: How do you authenticate? How do you complete a typical workflow? What conventions are used?
Is there rate-limiting, meaning do you have to watch out not to make too many calls? Do some calls not gratis or even expensive to make? Are there any side effects of calls I should know about?
If the REST API is fully specified with OpenAPI and has an accessible Swagger/Redoc page, it already goes a long way. Even better if there is additional documentation helping you make the first steps and showing how the different endpoints are used in combination.
A bad REST API is inconsistent, not documented at all, and has different non-standard authentication mechanisms. Also, like any software, bad APIs have bugs and times when they are down.
With the last sentence, you can notice an interesting effect: As users, we start to distinguish no longer between the interface and the service. It would have been more correct to say that the service had implemented the API wrong and the service which implemented the API was down. But in many cases, people use “API” and “the service behind the API” as synonyms.
The service itself is just software and thus has functional and non-functional requirements. The functional requirements are the things you want to be able to do. If the API is an interface to your library, you might have the requirement to order a book or to see your currently rented books.
Non-functional requirements are about how you’re doing things: Is the service up/available 99.9% of the time? How quickly does it respond most of the time?
An API is a contact point that allows services to communicate. It needs to be documented in some form for others to be able to use it. OpenAPI is one way to specify REST APIs. Using the OpenAPI specification, you can use Swagger or ReDoc to document the API.