See what makes Kong the fastest, most-adopted API gateway
Check out the latest Kong feature releases and updates
Single platform for SaaS end-to-end connectivity
Enterprise service mesh based on Kuma and Envoy
Collaborative API design platform
API and Microservices Security for Gateways, Service Mesh, and Beyond
Call for speakers & sponsors, Kong API Summit 2023!
6 MIN READ
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.
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:
Because RESTful APIs 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.
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 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:
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.
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 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.
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.
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.
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:
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!