What’s an API?

One of the first questions we should answer here is, what’s an API? As mentioned in the introduction, it’s an application programming interface, but what does that even mean?

In general terms, it’s an interface for programmers to interact with an application. However, there are different definitions of an API, depending on the context. One of them could be the set of methods/functions that are exposed by a library. That’s known as a library API. Of course, as a software engineer, you’re dealing with these kinds of APIs all day long – your Go packages, your exported functions, and the standard library are all APIs, but they focus on in-process communication, organizing your code, and separating concerns. But, in modern systems, when we talk about APIs, we’re usually talking about remote APIs.

So... what’s a remote API? A remote API is a set of functionalities that are exposed to other processes, generally through a communication channel (such as a socket), allowing independent programs to interact with each other.

But that’s still abstract, so let’s be more specific about what we’ll discuss in this book. We’ll talk specifically about REST APIs, one of the most common ways of inter-process communication used today. In REST, the communication channel that’s used is an HTTP connection that uses the HTTP protocol, so the API behaves like a web server and uses the same technology to communicate with other processes.

Before we explore REST and why we chose it over other options (maybe the best option for you is a different one), let’s explore the most popular options that are available.

GraphQL

GraphQL is one of the modern approaches to providing APIs. It was born from the necessity to provide more flexible APIs to consumers without enforcing a rigid structure (REST APIs are normally less flexible for consumers). It has a lot of exciting advantages, such as the ability to request only specific fields or embed substructures in the same response on demand by asking the client for it. That’s all doable in REST, but it isn’t standardized like it is in GraphQL. GraphQL is a great option when many clients access your data in very different ways and patterns, and you must provide that flexibility. Also, GraphQL provides lots of value when you don’t know how the consumer will query your data.

gRPC

gRPC Remote Procedure Calls (gRPC) is also one of the newest approaches for creating APIs. It’s widely used in Go and has a lot of advantages. One of the main advantages is that it’s agnostic from the language, and most of the code for serialization/deserialization and remote calls is automatically generated by the tools available. The degree of communication performance in gRPC is outstanding for multiple reasons, but mainly due to its binary protocol and usage of HTTP 2 as the transport layer. gRPC is ideal for the internal communication of services/microservices but isn’t widely used in things such as web applications or public APIs. This is because HTTP 2 is a requirement and developers are normally more familiar with other technologies, such as REST.

SOAP

Simple Object Access Protocol (SOAP) is a very old technology that uses similar principles to gRPC. It uses HTTP as a transport layer, and the protocol is 100% XML. The main problem with SOAP is that compatibility between libraries is suboptimal. SOAP works well when you use the same library and language in all the services that you’re communicating with, but not so well when you have a heterogeneous environment. Also, web clients rarely use SOAP as a communication protocol.

Custom API

You can build a custom API mechanism, selecting how you serialize and deserialize the data, transport it, and define the actions you allow. You could define a whole protocol and use TCP to communicate directly, but that’s normally not needed, and there are a lot of problems that have already been solved in the previously explained technologies and, of course, in REST.

I’m adding this option for completeness, but unless you know why you’re deciding to go with this option, you should probably be using one of the existing well-known solutions.

In summary, there are multiple mechanisms for generating APIs and communicating with applications, but in this book, we’ll be using REST. So, what’s REST, and why should you use it?