When it comes to API’s, you traditionally will opt for a RESTful API that returns JSON data. The REST approach has served us well for many years, but as web applications have evolved and grown in complexity, so too, have the needs of what API’s do. Fortunately, the smart folks over at Evil Inc (Facebook) created something called GraphQL, which is one of the best things to happen to APIs since REST.

Instead of defining controllers in your API and making calls to your database via rigid actions, GraphQL allows the client to query for the data using a JSON-like format. It can do reads, writes and updates like a traditional REST api, only you don’t have to bother your backend team to add in new controllers, actions or touch existing ones and potentially break other parts of your application.

The true value in GraphQL is the ability to implement new features or update existing ones on the client-side without requiring anything else. If you have to make some changes to your application, you can do so in a safer manner.

Couple this with the fact that GraphQL requires you to define your schema and type said values in the schema and you know that the type of data you are querying is the type of data that is being returned.

If you opt for a decent server (I highly recommend Apollo Server) some of the painful aspects of GraphQL such as caching and query complexity have been solved and documented for your convenience. Some of the lighter and in my opinion, inferior options for implementing GraphQL on the server-side give it a bad name as they generally do not deal with these problems for you (at least not out-of-the-box).

In my experience, a properly implemented GraphQL solution should be easy to maintain and equally, easy to understand and improve. In all of my uses of GraphQL, I make sure my resolvers are simple and easy to follow. A resolver is just a simple function that returns data and in some instances, one or more arguments for filtering and querying data.

On all of my side-projects, I have moved to GraphQL and I generally host it within a Firebase Cloud Function, with minimal work in my resolvers to communicate with my database and return data. Where I possibly can, I will always opt for GraphQL over REST because it is vastly superior.

As with anything, you should not default to choosing GraphQL for every single use case. As great as GraphQL is, it does introduce a little more complexity into your stack, it requires a little more configuration. For medium to large applications dealing with a lot of data, you will see the true value of GraphQL quite quickly. Small hobbyist projects, perhaps not so much.

Some of you might know that I spend my time immersing myself in the latest and greatest technologies and a couple of years ago got active involved in cryptocurrencies and blockchain.

The rise of GraphQL has become too high to ignore. Unlike traditional RESTful API’s, GraphQL uses an expressive query language to allow you to query your server for the pieces of data that you need, leaving the implementation details on the server in resolver functions.

At the start of 2019, I open sourced a GraphQL implementation over the top of the Steem blockchain, specifically a layer on top of the Steem blockchain called Steem Engine. I named the library Steem Engine QL. If you are not aware, the Steem blockchain is a fast blockchain with no fees and 3 second block times. It is perfect for content, decentralised applications and other use cases where you need a fast open source blockchain.

GraphQL is a perfect fit for blockchain

After creating my initial implementation one thing that stood out immediately was how much easier it made querying the blockchain and returning data.

In some instances, I needed to combine data from multiple sources and return it in the one request. On the client-side, this would have taken two API requests, then taking the results, filtering and combining into the final structure. Now, this happens on the server and the API returns everything as one. A good example is the coinPairs type here.

On the front-end, that coinPairs data is fetched like this (the code is located here):

query {
  coinPairs {
    name,
    pegged_token_symbol,
    symbol
  }
}

GraphQL === Fast Feature Iteration

Having used the above GraphQL server implementation in a large-scale open source project one of the biggest benefits is the ability to iterate and implement new features.

Instead of having to write implementation logic on the server to return needed data, once all of the query types and resolvers have been implemented, you just query for what you need. If a REST API were being used, it would require continual development work to add in new endpoints and maintain existing ones.

Because GraphQL promotes typing your resolvers and return types, everything is self-documented, so you know what the server supports and returns data wise. This is an area where REST simply cannot compete, and I am a huge TypeScript fan so it aligns with my code quite nicely.

Case in point, just yesterday in a few short hours of work, an entire new feature was implemented into the codebase without requiring any API work whatsoever. Most of the work was simply just UI, querying the API for the needed pieces of information.

Why Apollo?

I tried a few different GraphQL implementations before settling on Apollo for the server. The thing with Apollo is that the company seems comitted to open source and is well-funded as well. It has great integration with numerous frameworks and libraries, and has sorted out some of the painpoints in GraphQL: namely caching and request batching support using DataLoader.

On the other side of the stack, the Apollo Client library makes querying the Apollo Server a breeze, with support for caching including an in memory cache which does a fantastic job caching your GraphQL queries.

You can find the code for Steem Engine QL here and see it being used in an open-source application here.