REST, GraphQL and gRPC are all commonly used methods for allowing two software components to communicate with each other. They define architectural patterns (or protocols) that govern how connections should be made and data should be transferred.
Most developers are familiar with REST, as it is probably the most widely used protocol on the web today. However, GraphQL has boomed in popularity over the last ten years, and gRPC is also seeing more widespread adoption for certain use cases.
In this article, we’ll look at all three design choices, talk about the ways in which they’re different, and discuss which you might choose for your project, and why. We’ll also look at some real-world examples.
Table of Contents
What is REST?
REST is short for “Representational State Transfer” and outlines a set of procedures for sending requests between a client and a server. REST isn’t a language or a framework – rather, it is a set of standardizations that manage how resources should be operated on and transferred.
HTTP
The primary component of REST is HTTP (Hypertext Transfer Protocol.) HTTP is the “layer” at which web requests are sent and handled. It comprises a set of methods that allow for stateless communication between a client and server – meaning neither the client or server has any memory of previous requests when handling the current request.
HTTP Methods
HTTP methods allow you to perform CRUD (Create, Read, Update, Delete) operations on a particular resource.
- GET – retrieves data from a server
- POST – pushes data to a server
- PUT – replace an existing resource
- PATCH – update an existing resource
- DELETE – delete an existing resource
In practice, many developers use either GET or POST requests to perform the majority of operations.
REST APIs
REST APIs are organized around resources that are exposed via endpoints. These endpoints allow a client to request or update information as needed using HTTP methods. To be considered a true REST API, the API must:
- Have client-server architecture (i.e. client and server are decoupled)
- Maintain statelessness between client and server
- Allow for RESTful resource caching
- Have layered or decoupled architecture (i.e. client doesn’t need to know about all endpoints to use it)
- Have a uniform UI
- Code on demand (optional)
A REST API typically exposes an endpoint for each resource, and allows the client to provide “query parameters” to filter the results or perform certain operations.
The Benefits of REST APIs
REST APIs are simple and flexible. They are language-agnostic and most return information in easy-to-digest formats like JSON or XML.
Another benefit of REST is that it is already widely used, so developers can pick it up easily, and support is not difficult to find. There is a strong community surrounding REST, and a lot of existing tooling to make using it more efficient.
Finally, REST is incredibly uniform across the world, so it is very easy to get up and running with a new endpoint, or incorporate a new endpoint into your existing architecture.
A Real-World Example: The IPstack Geolocation API
APIs are incredibly useful for accomplishing routine tasks that you’d rather not code yourself. One common use case is geolocation – determining the location of a user who accesses your site or app. This is useful for things like geofencing, targeting advertisements based on user location, sending location-dependent updates, etc.
Let’s take a look at how the IPstack geolocation API helps you do this.
1. Get an API Key
- Sign up at https://ipstack.com to get your free or paid API access key. The free tier gives you up to 100 free requests per month.
2. Make the API Request
- Send an HTTP GET request to the following endpoint, appending the IP address you want to know the location of, and your API key as query parameters
http://api.ipstack.com/{IP_ADDRESS}?access_key=YOUR_ACCESS_KEY
You can test this out by sending the request directly from your terminal using the cURL command:
curl "http://api.ipstack.com/134.201.250.155?access_key=YOUR_ACCESS_KEY"
3. Interpret the Response
- You’ll get a JSON response like this:
{
"ip": "134.201.250.155",
"city": "Los Angeles",
"region_name": "California",
"country_name": "United States",
"latitude": 34.0438,
"longitude": -118.2512,
...
}
From here, you can pull needed values (like the latitude and longitude) off the response object and use them in your code.
IPstack includes an optional security parameter, which you can use to gather security information about the IP address. You enable this by adding an optional security parameter with a value of 1. This will return an additional field on the response object with security data:
{
is_proxy: false
proxy_type: null
is_crawler: false
crawler_name: null
crawler_type: null
is_tor: false
threat_level: "low"
threat_types: null
}
What is GraphQL?
GraphQL is a query language originally developed by Facebook, that enables an API to develop a schema that clients can execute complex queries against. Rather than exposing separate endpoints for creating, updating, and deleting data (and often, several separate endpoints for querying each resource) GraphQL uses a single endpoint.
How Does GraphQL Work?
Under the hood, GraphQL still relies on HTTP to send requests. But rather than using GET, POST, PUT, PATCH & DELETE, the key components of a GraphQL API are queries, mutations and subscriptions.
Queries
Queries are sort of a parallel to REST API GET requests. They allow a client to retrieve a resource from the endpoint.
Mutations
Mutations can be thought of as similar to POST requests. They allow the client to send or update a resource.
Subscriptions
Subscriptions function similarly to web sockets, establishing open, bi-directional communication between client and server.
The Benefits of GraphQL
GraphQL allows the client to dictate the shape of data, rather than the server. Essentially, instead of the server telling you what shape of JSON object you should expect to receive from a particular endpoint, GraphQL exposes just one endpoint and lets the client send very specific parameters than return exactly and only the data the client needs. Then, GraphQL collects data from various different sources (databases, other APIs, etc.) and combines them all into a single output.
One of the primary drawbacks of REST is that a client often ends up over-requesting or under-requesting data – meaning an endpoint will always send back a JSON object of the same shape, regardless of how much data the client actually needs from that object.
A Real-World Example
Take the APILayer IPstack API. The full response that the endpoint sends back looks like this:
{
"ip": "155.52.187.7",
"type": "ipv4",
"continent_code": "NA",
"continent_name": "North America",
"country_code": "US",
"country_name": "United States",
"region_code": "MA",
"region_name": "Massachusetts",
"city": "Boston",
"zip": "02114",
"latitude": 42.36235046386719,
"longitude": -71.06477355957031,
"msa": "14460",
"dma": "506",
"radius": null,
"ip_routing_type": "fixed",
"connection_type": "tx",
"location": {
"geoname_id": 4930956,
"capital": "Washington D.C.",
"languages": [
{
"code": "en",
"name": "English",
"native": "English"
}
],
"country_flag": "https://assets.ipstack.com/images/assets/flags_svg/us.svg",
"country_flag_emoji": "🇺🇸",
"country_flag_emoji_unicode": "U+1F1FA U+1F1F8",
"calling_code": "1",
"is_eu": false
},
"time_zone": {
"id": "America/New_York",
"current_time": "2024-06-13T09:37:03-04:00",
"gmt_offset": -14400,
"code": "EDT",
"is_daylight_saving": true
},
"currency": {
"code": "USD",
"name": "US Dollar",
"plural": "US dollars",
"symbol": "$",
"symbol_native": "$"
},
"connection": {
"asn": 40831,
"isp": "Mass General Brigham Incorporated",
"sld": null,
"tld": null,
"carrier": "mass general brigham incorporated",
"home": false,
"organization_type": "Hospital",
"isic_code": "Q8610",
"naics_code": "000622"
}
}
As a developer, you might only need the latitude and longitude – meaning the response contains a lot of data you won’t use. In most cases, this isn’t a problem, but if you’re developing for a very lightweight app that runs on an outdated mobile device on a slow network, this could have performance repercussions.
What is gRPC?
gRPC is a very specific protocol developed by Google as a fast, lightweight bi-directional streaming service. Similarly to REST and GraphQL, it outlines a “contract” or standardization for communication between a client and server.
The main difference between gRPC and REST or GraphQL is that gRPC returns data in binary, using protobuf, as opposed to a human-readable form like JSON. This means you need a proxy or gRPC-web interface to use it in the browser, and the learning curve to get up and running is much steeper.
The Benefits of gRPC
gRPC is extremely fast and lightweight, but in general, only useful in a handful of specific cases. It’s good for communication between microservices on the backend, but not so useful between a client and server. It can also be good for use by mobile apps on flaky networks.
For the most part, gRPC is overkill for a public API.
When to Use REST vs GraphQL vs gRPC?
These days, REST is still the dominant method of communication on the web. Most public-facing APIs expose REST endpoints to allow access to their resources. For example, the IPstack API we looked at earlier, as well as other APILayer services like Mediastack (which provides access to up-to-the-minute news headlines), Aviationstack (which returns real-time flight data) and Marketstack, which returns real-time stock data.
The majority of publicly available APIs that you might want to incorporate into your app use REST.
When building your own API – for example, to use internally with your team or to expose your team’s software to the rest of your company – GraphQL might be a good option. It can be layered on top of existing REST APIs, so the transition to using it can be rolled out slowly without breaking changes.
GraphQL or REST can be used to build new public-facing APIs, and GraphQL is especially useful in cases where rapid prototyping is needed, or the frontend has a lot of dynamic requests.
In general, gRPC can be used for high-performance internal APIs.
Conclusion
If you’re just getting started dipping your toes into the world of APIs, we recommend checking out APILayer to test a few out. All the APIs have free tiers that allow you to get up and running quickly and do rapid prototyping of MVP applications.
FAQs
Which is better, GraphQL or REST API?
GraphQL and REST APIs are both effective, and the choice to use REST vs GraphQL is purely about which protocol meets your needs and what is available. There is no “one that’s better than the others” ; they are simply different tools for different things.
What is the GraphQL vs REST API endpoint?
A REST API endpoint exposes a single resource and allows the client to filter that resource or perform different operations on it using query parameters. GraphQL exposes a single endpoint for all resources and allows the client to dictate the shape of the returned data based on a schema.
Should I stay with REST or move to GraphQL?
There’s no reason to move to GraphQL unless you’re running into issues with your existing REST API. If your API is simple and stable, there’s no need to change anything. However, if you’re finding that clients are consistently under or over-requesting, or that requesting multiple resources is becoming expensive and downgrading performance, then you might want to consider switching to GraphQL.
