An Application Programming Interface, commonly referred to as an API, is a means of communication between two software systems. Let’s imagine we have a system called A and another called B. B needs certain information from A, so B calls A’s API to obtain it.
For this to work, A needs to expose, in some way, a public interface. This interface is typically documented so that B can understand how to request information from A. A may also have a private interface that B cannot access, meaning it is not exposed and, therefore, restricted to B. This latter case is called a private API.
There are all kinds of APIs, and while REST APIs are the first to come to mind for most developers, they are not the only ones. This article will delve into the most popular API architectures, such as REST and GraphQL, and break down their different characteristics to better understand their main differences.
How do APIs work?
At its core, APIs act as intermediaries between two software components, defining clear rules on how data is sent and received, what actions can be performed, and how it should be done. This set of rules is called a standard, and both parties must implement it to be able to understand each other.
Using APIs facilitates communication between systems, as they don’t need to know all the internal details of each other’s implementation. Instead, they just need to understand how to interact with the provided API.
In the specific case of web APIs, communication occurs between a client and a server. The client initiates a request to obtain information from the server, and the server receives this request, performs the necessary calculations, and returns the results to the client. In other words, client and server communication occurs through requests.
What types of APIs are there?
Although we commonly use the term API to refer to web APIs, this is not necessarily the case. APIs serve as a universal way for two software components to communicate, regardless of whether they are web-based or not. While all web APIs are APIs, the opposite is not always true (not all APIs are web APIs). APIs are versatile tools that any type of software can use to interact with another.
When we talk about web APIs, we are referring to a subset of APIs specifically designed to operate over a network, and although we typically refer to the internet, it can be any other private or local network. Communication in a web API occurs through what are called endpoints, which we will explain next.
What is an API endpoint?
An API endpoint is an access point represented as a URL, allowing a client to interact with a server. Each endpoint in an API is associated with an action on the server, such as requesting information, creating new records, or updating existing data.
When an endpoint is executed, it initiates a request on the server. Upon receiving it, the server processes and returns the result to the client. This back-and-forth exchange occurs through the HTTP protocol using TCP sockets, and information is transmitted through HTTP messages.
An HTTP request contains primary data, such as the type of operation (e.g., GET, POST, PUT, DELETE), the specific API endpoint, and any additional parameters or data required for the operation.
Upon receiving a request, the server performs necessary actions and then generates a response containing the result of the requested operation, along with other relevant data. The client returns this response through the same TCP socket and HTTP protocol.
How to Create an API?
When creating a web API, there are multiple architectures to choose from, each with its characteristics, advantages, and specific use cases.
Two of the most popular and widely used architectures are REST (Representational State Transfer) and GraphQL. While both are reliable, they follow different philosophies. Therefore, if you’re about to start building your API, choose the pattern that aligns best with your requirements.
REST vs GraphQL
REST, the most popular paradigm for building APIs, is a software architecture that heavily relies on HTTP methods and uses multiple endpoints to exchange information between the client and the server. However, a notable characteristic of REST is that its endpoints often return more data than is strictly necessary, which can cause excessive network traffic.
In contrast, GraphQL takes a different approach. Instead of being an architecture, GraphQL is a language that describes how a client should obtain data from a server. In the GraphQL paradigm, only one endpoint is exposed, and developers who use it request only the information they need from the server. This characteristic of GraphQL allows for reducing the transmission of unnecessary data over the network.
While REST and GraphQL provide mechanisms for developers to obtain information from a server, their different philosophies in endpoint usage and data transmission make them suitable for different scenarios and preferences in the broad field of API development.
