Rest vs GraphQL

GraphQL is open source specification to query data from Server. It was first developed by Facebook in 2012, and the specification was open sourced in 2015.

GraphQL shifts focus, from thinking the data as resource urls, to thinking of it as graph of objects and data model. For example the Employee and their Education and Experience data can be represented as below graph of object -

Employee {
    First Name
    Last Name
    Department
    Education {
        College
        Degree
    }
    Experience{
        Company
        duration
    }
}

Advantages

Let’s now look at some of the advantages of GraphQL over resource URL based REST paradigm .

1. Alleviates the issues of over and under fetching
   GraphQL provides a framework and language to query data from server. This ability helps client to query only fields that are needed and define the shape of response which reduces amount of unnecessary data transfer over the network. To illustrate this using our the graph above, the client can just choose to get First Name via GraphQL query, the same use case in Rest would lead to transfer of whole employee object.
2. Reduced number of API call in hierarchical data
   Imagine we want to get Employees in a department, and Education detail of each employee. The plain REST approach would require at least two API call to get this data. A solution built on GraphQL can mitigate this by having a graph data model as mentioned in our graph example above. One can argue that it’s possible to build a custom REST API that returns the data in one call, though it would open up another issue of API management.
3. Query language framework
   The query language provides a framework to specify metadata i.e. data attributes to fetch, data attribute value, filter on data etc. This metadata can be used to provide useful functionality to client such as filter data based on values, specify data pages etc.
4. Data model stitching
   The framework supports data model stitching using resolver. What it means is that it inspects the client graph query and identifies corresponding resolver to get the data, and finally stitches it together before rendering the response.

Concerns

1. GraphQL exposes single end point and works with query language. Because of this , there is no globally unique end-point for each request variation for client side caching. Hence client side caching requires extra considerations such as globally unique identifiers, client side caching library like apollo client.
2. The API call in GraphQL always returns HTTP Status code 200, and in the event of an error, the response is wrapped with error object that needs to be inspected. This makes error handling bit complex.
3. As client has a lot of flexibility in terms of what to query next, the Server side caching is not straight forward and is challenging compare to plain Rest APIs.

Conclusion

GraphQL has distinct advantages for data use cases that are hierarchical, needs to be mashed, needs to be aggregates, and needs to be filtered. Most of these benefit stem from shifts of focus, from thinking the data as resource urls, to thinking of it as graph of objects, and providing a query language on top of it.

Moreover, the GraphQL implementation exist in major languages, and is open source.