REST API vs GraphQL vs gRPC

Application Programming Interface (API) allows developers and clients to conveniently communicate with backend services and receive the responses they expect. REpresentational State Transfer (REST) APIs are among the protocols used by such companies as Amazon, Netflix, Uber, Spotify, Salesforce, and others to integrate different services and data and improve user experience. They also apply gRPC, GraphQL, and other protocols for specific needs.

Why APIs Matter?

API-based architecture is characterized by the abstraction of implementation detail. This means that developers can make quick changes, update, or replace components in the back end, and the consumers will not be impacted as the API contract does not change.

Modern microservices architectures and service-oriented architectures lead to rising numbers of separate services. Those services may run simultaneously. Therefore, there is a necessity for developers to coordinate the processes and address the challenges of distributed communication. A variety of API protocols, including REST, gRPC, and GraphQL assist software developers in solving those issues. However, it is essential to know the differences between available options and how to choose the right solution for a particular business domain. APIs should be useful tools for DevOps, not a bottleneck or a deployment constraint.

When Is the REST API the Right Choice?

Deciding which API standard will be the right one to adopt involves answering the following questions:

• What are the other standards that the company has, if any?
• Is it possible to extend existing standards to external consumers?
• How are consumers impacted by not having a standard?

At Belitsoft, we recommend choosing a standard that best suits the culture of the company and existing API formats. Our developers analyze the current situation and suggest custom API integration with third-party applications if necessary. For example, one of the Belitsoft clients working in the sphere of transportation management spent much time manually processing documents and addressing several applications to check the status of loads, handle insurance, etc. Our experts set the required API integrations with carrier marketplaces, onboarding services, load-tracking apps, accounting platforms, and others. The company automated its main workflows and improved customer service.

REST APIs support both service-oriented and microservice-based architectures. REST APIs use HTTP, which makes them easy to understand and implement. REST was developed as a standard that describes how to interact with a system. For example, GET requests are used to get data, DELETE to remove data, and POST to add data. The client specifies what they want to interact with and the format of data that they expect in the response.

Another characteristic of RESTful APIs is that they are language-agnostic. In combination with standard HTTP methods, it makes REST API an available and low-barrier entry option for both clients and servers.

On the other hand, REST is not strictly typed. For example, the POST request can get data, add, modify, and delete, depending on how the handler of a particular request was implemented. That is why it sometimes brings confusion about what a particular query is used for.

REST vs GraphQL

As with REST, GraphQL works on top of the HTTP protocol and is fully supported by all browsers. That is why both API architecture styles are ideal when developing a web app with a necessity to interact with a backend service or integrate with third-party services. The main characteristics of GraphQL are the following:

• GraphQL is an open-source language used to get data for specific fields in a single request to the server. It decreases the number of requests to the server when these fields are stored in multiple entities. However, it requires the developer to know how to build a query correctly in order to get the necessary data.
• GraphQL offers a single version across all APIs. It means there is no need for complex management of multiple versions on the consumer side.
• GraphQL works best with data and services from a particular business domain. If you have many external, disparate APIs, GraphQL might not be the best choice as it will add complexity.

REST vs gRPC

Remote Procedure Call (RPC) APIs execute codes or functions of other processes. RPC APIs access internal systems and reveal the details to the user. REST APIs hide those details. gRPC is a developing open-source and high-performance RPC framework created by Google for communication between servers or services. Here are the main features of gRPC APIs:

• gRPC provides a faster exchange of messages between services, and the messages weigh less, which reduces the amount of data transported through the connection, thus freeing up the connection faster.
• The gRPC protocol is typed, i.e., developers create a special file describing all messages and types of data they will send and receive before the implementation. The downside is that modern browsers do not have full support for this protocol, so they usually use an API Gateway. The frontend sends a query to the API Gateway using the HTTP protocol (REST, GraphQL), and the uses gRPC to send messages to the required service to process the request.
• REST APIs are stateless, i.e. the requests contain all the necessary data and do not relate to previous interactions. gRPC APIs can be both stateless and stateful. It depends on the implementation.
• gRPC allows access to multiple individual functions, but it is not usually used to extend a resource model. REST APIs perform that.
• gRPC can be successfully used for high-traffic services and for the two services under tight producer control.

Best Practices and Trade-Offs

When business grows, it becomes necessary to adapt APIs to the changing environment. API versioning is a way to manage REST API alterations without affecting existing integrations.

API Versioning Best Practices

• Release a new API version and deploy it in a new location. Legacy applications continue working with an old API version. It is okay for a consumer, as they upgrade to a new location and new API only if they demand new functionality. At the same time, the owner has to maintain all versions of the API and make timely corrections and bug fixes if it is required.
• Release a backwards compatible API version. In this situation, it becomes possible to add changes without affecting existing users. Consumers do not need to upgrade the system immediately. However, the downtime should be taken into consideration and the availability of both versions at the time of the upgrade. Even small bug fixes might cause serious issues.
• Break compatibility with an old API and ask consumers to upgrade the code. This scenario may bring unexpected interruptions in production. However, sometimes there is no opportunity to avoid compatibility problems with older versions. This is what happened in 2018 when the GDPR (General Data Protection Regulation) was introduced in Europe.

The options mentioned above have advantages and disadvantages for both consumers and API owners. Software development firms like Belitsoft support the combination of those three options. To do that, we use a semantic versioning approach. What does it stand for?

Semantic Versioning

This approach is used in software development to manage versions. It assigns numbers to API releases and divides API versions into three groups.

• Major version: This one is non-compatible with the previous API. Consumers have to upgrade to a newer version. They are usually supported by a migration guide and careful monitoring.
• Minor version: It is a backwards compatible change with the old API version. Users do not have to change their code.
• Patch version: This version does not bring new features or changes to existing functionality. Developers fix bugs and errors with this version.

API Lifecycle

Discussing the API lifecycle with consumers is an important part of API development and integration. Clients understand what to expect if they know the stages that an API passes. A combination of semantic versioning and API lifecycle allows consumers to track the releases of the major APIs leaving minor and patch updates without their participation. Here are the stages of the API lifecycle according to the PayPal Standards:

• Planned: This stage is about discussing what you are going to build and what services this API should cover.
• Beta: It is the first version of the API to receive consumers’ feedback. Users start to integrate with a new API and provide their ideas for improving it. This stage allows developers to avoid building several major versions in the beginning.
• Live: At this stage, the API is in production. Any changes become versions. When a new version appears, the current API becomes deprecated.
• Deprecated: Such APIs are not developed any further, but they can be used. When a minor version appears, the API is deprecated only during the validation of the new version. When the new version is validated and compatible with all services, a minor one moves to retired. When a major version comes out, the previous one becomes the retired one. However, it does not happen at once, as consumers need time to migrate.
• Retired: The API is not accessible anymore.

If you are looking for specialized API expertise, improved API quality, and a scalable API team, the Belitsoft software development company offers outsourced services to meet your expectations. Contact us today and we will discuss your project requirements.