Introduction

For many years, REST was the de facto standard for building APIs (Application Programming Interfaces). But in this rapidly evolving digital landscale, businesses have started to use different architectures when building APIs. Today we will discuss what APIs really are and the difference between the top 3 most used APIs right now - REST, GraphQL and gRPC.

What is an API?

The definition of the API is exactly what its name says. It is an application interface that gets consumed by other applications, which then returns a response, for example data. It is in its simplest form a set of rules and protocols that allow one piece of software to communicate with another.

Let's consider an example that everyone uses on a daily basis. You want to log into an application, and there is a login form in your browser. You enter your credentials into the form and click on the submit button, and you are logged in. But while you clicked on send, there was tons of stuff happening behind the scene. First, the frontend takes your credentials and sends it to the API. Usually, you'd use a REST API for this use case (we will dicuss REST shortly). Then the REST API checks if the credentials have a match in the database. If they do have a match, the API returns a HTTP status code 200, which means the request was a success, and a cookie or OAuth token to persist the user session on page refresh.

Of course, this was the example of the most basic use case. You could also fetch data from a database and return it to the frontend, create new entries in a database, update data or delete data. Those API requests are also known as CRUD (Create, Read, Update and Delete), and they form the backbone of every API there is, no matter its type.

REST API - The API powerhouse

REpresentational State Transfer is the most popular API architecture type because of its simplicity and flexibility. Focused on representing application state through web resources, REST uses HTTP verbs, each of which serves a narrow purpose:

• POST: create new resource.
• PUT: update a resource entirely if it exists or create it if it does not.
• DELETE: delete a resource.
• PATCH: update an existing resource partially.
• GET: query for an existing resource or resources.

Benefits and drawbacks of REST

They are so wildly used, most developers are already familiar with them. Because REST aligns closely with the design of the HTTP protocol, browser and other HTTP clients will natively understand requests from RESTful APIs.

REST isn't are cure-all though, which is why it's not the only API architecture out there. RESTful APIs can result in bloated responses, especially if resources are particularly complex, which is one of the drivers of the rising popularity of GraphQL. The flexibility of RESTful API development also puts the onus of adhering to principles and standards on the developer. While the OpenAPI specification is a great tool for this, sticking to it must be an active decision, since RESTful APIs are not inherently self-documenting.

When to use REST API

If you don't have a compelling reason to choose otherwise, REST is probably the best option for your application. While GraphQL or gRPS might fit use cases with unique needs, it's more often the case that you just want to build with a good, solid API approach. For its shallow learning curve, a massive ecosystem of wealth of publicly available examples to learn from, you should consider REST APIs as your default choise.

GraphQL - Data fetcher

GraphQL is an API query language designed to provide a more streamlined and queryable API for mobile applications. GraphQL APIs are popular for implementations with highly complex schemas in which only subsets of data are needed.

It's much easier to understand GraphQL by seeing an example request and response. Let's consider the Countries List GraphQL implementation. This API exposes continents and countries as resources. Let's see what an example request and response might look like:

On the left, notice that you must indicate what fields you want to receive from the API. There's no option to request all continents without indicating what you want to know about them. In the above request, we asked for the name and code for each continent.

We would have slimmed down the response payload by asking only for code but not name. The gain in this example is minimal, but consider a massive table with dozens of columns. With a REST API, a GET request might get everything about every record. With GraphQL, the client only receives and processes the data they need.

Benefits and drawbacks of GraphQL

GraphQL lets developers be laser-focused in their queries, plucking out only the data they want.

While this flexibility is a benefit for the client, it is also a drawback for the server developer. Somebody needs to do the heavy lifting so server performance can be unpredictable. The full customization of requests also means that server-side caching is very difficult. These difficulties do translate to a steep learning curve for API developers looking to take a GraphQL approach.

When to use GraphQL

If you aticipate there will be many ways clients will consume your data, GraphQL can be an ideal choice. Empowering API consumers may mean more work on the back-end, but it will likely make your APIs easier to consume.

Suppose your applications need highly structured information to build out your interfaces or populate the information displayed in your applications. In that case, GraphQL can be a great way to cut down on the number of requests you need to make to your servers.

gRPC - Lightning fast

(gRPC)[https://www.ibm.com/think/topics/grpc] was designed and developed by Google, so it is sometimes referred to as Google Remote Procedure Calls.

gRPC is an evolved design of the more generic concept of remote procedure calls. It allows a client to call a method on a remote computer directly as if that system was local. gRPC makes use of protocol buffers (or Protobufs) to define a typesafe interface with data serialized into binary - rather than text-based JSON or XML - for data transfer. It also makes use of the speed and efficiency of HTTP/2 which is more reliable and faster that HTTP/1.

gRPC APIs have four different service methods:

1. Unary: The client makes a single request to the server, and the server returns a single response.

2. Client-Streaming: The client streams a series of requests to the server, followed by a message to indicate the stream is finished. Then, the server returns a single response.

3. Server-Streaming: After the client sends a single request, the server responds by streaming a series of messages. The stream continues until all messgages are sent or the client disconnects.

4. Bidirectional Streaming: An initial connection is established between client and server, and either can send messages as needed, or either can terminate the connection.

Benefits and drawbacks of gRPS

Using Protobufs for data serialization, gRPC provides an incredibly lightweight and fast API. Because it is so lightweight, gRPC is often used when the client may not have much computing power (such as IoT). In these cases, the server does the heavy lifting.

gRPC also provides an excellent way to communicate between services written in different languages, given the language-agnostic definition of the interface contract. This makes the learning curve for gRPC—though not quite as shallow as REST—quite tolerable.

While gRPC is highly efficient, it isn't well supported by browsers. It can also be difficult to learn by experimenting in a sandbox. The usage of HTTP/2 is also likely to be unfamiliar to less experienced API developers.

When to use gRPC

If you need to squeeze every drop of performance out of your client machines, gRPC can be a great choice. This is why a widespread use case for gRPC is to facilitate communication among smart devices. Given their size, limited computing resources and real-time functionalities, IoT devices depend on the performance of gRPC to function. Deployment pipeline tooling and application monitoring systems can also be great applications for gRPC.

Comparing key differences

The decision of which API development approach to take begins with a deep consideration of your business and application needs. The following table highlights some of the key differences between the three approaches we've considered.

Conclusion

We have seen there isn't a one-size-fits-all approach to API development. Microservices have allowed for application functionality to be abstracted, enhanced and modified independently from other systems. If one part of your system requires a gRPC implementation, others could reasonably use a GraphQL API simultaneously, all while exposing something else using a REST design. This flexibility enables software engineers to build much more sophisticated software architecture than it was possible 10 years ago.