Table of Contents
A few days back, as part of the training series, I presented the team with three popular approaches to develop API driven services. The goal was to share some differences among REST vs gRPC vs GraphQL, so this could be used as a reference sheet when considering one of these options for any of our future projects. I discussed the advantages and disadvantages of each approach along with use-cases that would allow us to choose which approach is best suited for our needs. After my initial share on LinkedIn a week ago, I expanded this and add some more details, and sharing it as part of the Technology Rivers blog.
As a background, I have been working in the software development field for over 19 years, and have used and seen in action different types of web services and application interfaces for the integration of applications. All these different approaches have their pros and cons, places, and the software field continue to innovate and enhance as we learn the challenges and problems with the existing options. In my early career, TCP and UDP was the main option for low-level connectivity, whereas SOAP web services were the main option for high-level connectivity. Lately (maybe in the last 10 years or so), other options have gained more traction, and I would like to discuss the pros and cons of the following three in this article.
REST (RESTful Services)
REST had a long history and had been a defacto for web programming for over decades. It’s one of the most common approaches when building a web application, or exposing an API for the mobile app project, or any application integration need.
Some key notes about REST:
- Use HTTP protocol (usually but not required)
- Depend on HTTP Verb and Status Code
- JSON as payload (usually but not required)
- Must have HATEOAS (usually missed)
- Easy to scale – Because of the stateless nature, REST is pretty easy to scale. Usually, all you need to do is launch another instance, when the clients request data, your load balancer can now redirect these requests to new nodes/instances.
- Easy to integrate – With HATEOAS the client knows how to get the State of Resource on the fly.
- Performance – REST usually uses HTTP protocol, which is considered the most common way by the web servers and clients, for caching the requests.
- REST is hard – Yes! REST is hard. There are many constraints (especially HATEOAS) that were ignored by organizations to simplify the REST endpoint. Some organizations may establish an RPC over HTTP (which accepts any type of Verb and has a path like /get_user ) instead of REST.
- Over fetching – Usually, to fetch data for a view (Web page or mobile (Android or iOS) View or Fragment, etc) we need more than one request. Sometime you will have more data than you wish to because it depends on the one behind the server (also called over fetching)
- No uniform style for documentation – Some may use Postman to test as well as documentation, others may use Blueprint, Swagger/OpenAPI, RAML. In our projects, we prefer to combine Postman and Swagger
- Versioning your API – field deprecation may cause many headaches.
Possible Use Cases
Some of the use cases where REST may fit:
- Commercial APIs: where each endpoint you will have different rate-limiting as well as ACL.
- Your data changes are not so frequent, and caching can help.
REST is still one of the most popular methods for creating API. Any major software company that provides access to its data, is still providing RESTful API as one of the main methods.
gRPC (gRPC Remote Procedure Calls)
gRPC is considered a fast and lightweight approach for data and preferred for scenarios with limited systems resources.
Some key notes about gRPC:
- Rely on HTTP/2 and Protobuf
- Streaming support
- Backed by Google
- Strong typed – Unlike REST (which is usually based on JSON), gRPC uses Protobuf — a structured message.
- Built-in code generator – Easy to write easy to read easy to create SDK.
- Because gRPC upon HTTP2, gRPC has almost all of the advantages of HTTP like authorization, request headers, …
- gRPC is pretty fast compared to other REST service techniques.
- A Proto file generally is a document itself. No more 3rd party tools needed.
- No built-in UI support for debugging/testing. You can’t just CURL an endpoint and it may be required to build a test harness. (*)
- Inability to leverage HTTP caching. (Every gRPC request will use the POST method)
- Over fetching
Possible Use Cases
Some of the use cases where you may prefer to use gRPC
- You need to create an SDK for mobile application.
- You want to avoid writing a client code (gRPC will generate client code for you, built-in load balancing, connection pool, etc…)
- When you need streaming or RPC style API then gRPC is a good way to go.
GraphQL is the new standard and becoming popular lately. GraphQL was released by Facebook in 2015 with different thinking of how clients can interact with data.
Some key notes about GraphQL:
- GraphQL isn’t about throwing away existing infrastructure, but leveraging it to the fullest.
- GraphQL is a specification, and by its nature, a specification is much stricter than an architectural style (compare to REST)
- JSON datatype.
- GraphQL has GraphiQL — a responsive UI for testing as well as a document browser for GraphQL endpoint.
- Clients have the ability to dictate exactly what they need and receive that data in a predictable way. (no more over fetching/data redundancy)
- Client applications can fetch many data from different resources by just one request.
- Strong typed.
- Provides introspection, the ability to query the API structure, and what data is presented.
- No official/built-in cache
- Circular queries can be a headache.
- Composite endpoints may difficult and hurt performance (also called schema stitching)
- Potential to expose the data model.
Possible Use Cases
Some of the use cases where you may prefer GraphQL
- You have complex objects (multiple levels of nested resources) and the data model is rapidly evolving
- You have stable REST APIs, RPCs, and want to leverage to one single endpoint.
What is best for my application?
One of the most common questions that is asked is which one is the best option for our option. Do we use REST, or GraphQL, or gRPC, or other options? And most of the time, the answer is, “It depends”. Every application has its own requirements, and selection criteria depend on many factors. In this article, we shared the pros and cons, to give you some insights so that you can make a better decision. If you are unclear, feel free to reach out to the API development experts, who can work with you and help you determine the right technology and API method for you based on your requirements.
This is a guest post by Irfan Azam, who initially posted the first version of this article here.
Irfan Azam is an expert software engineer and architect with over 2 decades of experience working in the software development field as a software developer, designer, tech lead, and software architecture. Irfan writes mostly about the software development field.