Not All Microservices Need to Be REST — 3 Alternatives to the Classic
By: Fernando Doglio
Tags: Programming, Soap, Api Development, GraphQL, Rest

GraphQL

Now, if you want to talk about new, GraphQL is the newest kid in town (I mean, it’s been out since 2015, but it’s still the hottest thing around, you know?).

While REST focuses on resources and provides a set of endpoints around them to allow for multiple operations, GraphQL focuses on the data. It is more a query language than an actual API, although it does provide all the required tools to access the queried data as well.

Don’t let the name fool you though, it’s not a graph database like Neo4J is, instead its major benefit is that it allows you to query and request the exact data you need. This can be a major benefit over REST, where you’d had to query multiple resources, get extra properties you weren’t really looking for and then mix it as part of the client logic.

Imagine having a simple API around a blog, with users, their posts and their followers. If you wanted to get the posts from one particular user, their name and the last 5 followers, you’d have to do something like this with REST:

//#1. Get user name

GET /users/<ID> /**

{

"id": "123",

"name": "Fernando Doglio",

"birthdate": "1983-10-24",

"address": {

"city": "Madrid",

"country": "Spain"

},

"phonenumber": 998392839

}

*/ //#2. Get user's posts

GET /users/<ID>/posts

/**

[{

"id": 1,

"user_id": "123",

"title": "Post #1",

"post_date": "2021-06-28",

"body": "...."

}

...

]

*/ //#3. Get last 5 followers for user

GET /users/<ID>/followers?orderBy=follow_date&desc=1&limit=5 /**

[{

"id": 1,

"user_id": "123",

"name": "Follower 1",

"follow_date": "2020-01-02",

},

{

"id": 2,

"user_id": "123",

"name": "Follower 2",

"follow_date": "2019-12-02",

}

...

]

*/

Notice there are 3 requests, and a lot of data I never mentioned as part of the ask (for instance, the user’s address nor the posts’ body). Now, it’s your client’s responsibility to discard the information it doesn’t need and then, mix everything together into a single object (or whatever data structure it may need).

Instead, if you were to perform the same query using GraphQL, you’d only have to do one single request that looks like this:

query {

User (id: "123"){

name

posts {

title

post_date

}

followers (last: 5) {

name

}

}

}

One single POST request with that information, we get all the data we need and because of how GraphQL works, the structure of the response will mimic that of the request. So we’ll get:

{

"data": {

"User": {

"name": "Fernando Doglio",

"posts": [{

"title": "Post #1",

"post_date": "2021-06-28"

}

...

],

"followers": [

{ "name": "Follower #1" },

{ "name": "Follower #2" }

]

}

}

}

As you can see, we’ve saved a lot of time only transferring the data we actually need and the client doesn’t have to do anything else, given the response is already formatted by the server.

This is especially helpful if you’re on a restricted network and need to take into consideration the cost of transferring data through the wire, like you would on a mobile device.

Another major benefit of GraphQL over REST is that you can get real-time updates from the server on specific events. This is usually done through a WebSocket connection, but it’s something that you could only dream about with REST.

This allows the communication to start on the server-side, instead of us having to code a polling mechanism on the client to get the new data as soon as we could (which does not mean as soon as it was accessible). This polling mechanism was also very bad for network traffic, given you’d be sending multiple HTTP Requests that would not yield any results.

Overall GraphQL is a major jump forward when it comes to data-intensive APIs because it helps optimize resource utilization. However, if your API is rather simple or is not meant to serve data-heavy use cases, going with GraphQL instead of REST could be overkill. Make sure that if you force GraphQL on your clients, they’ll be able to properly benefit from most of its features.