The proliferation of microservices has led to many new innovative approaches in the software world. However, building robust, quality APIs that consistently deliver the business outcomes you desire can be a complex task. It's no wonder a recent survey of organizations adopting microservices found that nearly 30% of the respondents listed "API quality" as one of their biggest challenges.
API-based applications don't just come in one flavor. Each API format has a unique set of advantages and disadvantages, and choosing which to use depends heavily on your specific application requirements.
In this blog , we'll explore the three most popular approaches to API development: REST, gRPC and GraphQL. We'll take a look at the benefits and drawbacks of each model and discuss how you can determine which API model best suits your needs.
REST API Architecture
REpresentational State Transfer (REST) is the most popular API architecture types in use today. Focused on representing application state through web resources, REST uses HTTP verbs, each of which serves a narrow purpose:
- POST: create a 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
What are RESTful APIs? They are so widely used, most application developers are familiar with them. Because REST aligns closely with the design of the HTTP protocol, browsers and other HTTP clients will natively understand responses from your RESTful APIs.
REST isn't a 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 behind the growing popularity of GraphQL. REST also may not be an ideal choice for very low-powered clients, which is what makes gRPC attractive in this case.
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 gRPC 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 resources and a wealth of publicly available examples to learn from, you should consider REST APIs as your default choice.
gRPC Architecture
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 than HTTP/1.
gRPC APIs have four different service methods:
- Unary: The client makes a single request to the server, and the server returns a single response.
- 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.
- Server-Streaming: After the client sends a single request, the server responds by streaming a series of messages. The stream continues until all messages are sent or the client disconnects.
- 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 gRPC
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.
GraphQL
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 nameand codefor each continent.
We could have slimmed down the response payload by asking only for codebut not name. The gain in this example is minimal, but consider a massive table with dozens of columns. With a REST API, a GETrequest might get everything about every record. With GraphQL the client only receives and processes the data they need.
Let's take another example, looking at the fields available when querying countries:
Fields on the countries resource as fetched through Kong Insomnia using native GraphQL support.
The following query will fetch the name, capital, and languages of all countries in Europe that use the Danish Krone as currency:
This is what the response payload looks like:
As you can see, we only received two results, but we did so with a single request. This query precision is what GraphQL was created to do, and it shines when we take full advantage of filtering and choosing specific fields to return for our records.
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 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 anticipate 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 client 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.
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.
To learn more about the top API models and when to use them in your next project, download the "When to use REST versus gRPC versus GraphQL" eBook today!