Notes on GraphQL vs REST for Data Architects

Statelessness in RESTful web services

REST is many things for many people. It doesn’t define a concrete set of rules as in, for instance, database normalization. It’s widely accepted that REST services are stateless in that the server doesn’t save the state of each request made by a client to a RESTful service. The client might save session info or cookies related to a service call.

The client may also request to modify the state of an application and the server will return the result. Both operations back and forth are handled through URIs, which can represented as links in the HTTP context. In this case when the application moves from one state to another (from the perspective of client), through invocations of RESTful services, the state of one request (ie, the execution of one RESTful service) doesn’t affect the state of another.

This is the predominant architecture of all web services development today. As with all architecture decisions, REST has its trade offs.

Drawbacks: Over-fetching, under-fetching, data binding & cultural issues

A RESTful service has a single endpoint for a given request. So if a client request require some data from server (say database server), there is only one end-point to fetch this data. Because this is a stateless architecture, provisioning just the parts of data (say 5 out of 10 attributes) based on current request isn’t possible.

For example, if customer date of birth is requested the response will include the entire customer record overloading the request (widely known as over-fetching problem).

Another drawback of this behavior is that web services developers often find it convenient to put their data in a single large chunk of NoSQL or JSON structure. The ethos of data architecture is to never do this mistake. Always structure your data — not just for the benefit of one service or one definition of web services development — but for the greater good of the organization. And this dichotomy creates a culture of lack of trust between Software Architects and Data Architects, both looking to build only the best solutions for their individual systems.

Another drawback is under-fetching. RESTful services has a definitive endpoint for each type of data. Customer data is one endpoint, Customer sign up data is another, Customer transaction data is yet another and so on. A request spanning many types of data will need to do many requests as they are separate endpoints, resulting in many roundtrips to the database server.

Data binding is an issue when the application has faster UI iterations resulting in different data requirements in each iteration. Because the RESTful service is bound to an endpoint which is bound to a data structure on the database, UI elements are also bound to this rigid setup.

GraphQL

GraphQL released by Facebook attempts to solve this conundrum by bringing in an additional layer of abstraction. Another trade off, not a silver bullet.

GraphQL introduces an API to define data on web services using a schema definition language that you can build on JSON. Using these JSON structures a client can now request for only as many data elements as it needs from the server. Because the schema layer is aware of data structures in the backend(yes it’s no longer stateless at this layer in that it’s schema aware), the JSON structure requested by client can be flexible and not necessarily the entire set of attributes from the table or document.

This solves the problem of having to over-fetch which in turn solves the problem of having to combine all attributes into one spaghetti JSON or table on the database server.

Problem of multiple roundtrip requests

GraphQL suffers from the problem of many roundtrips to the server as is the case with traditionally under-fetched REST requests. GraphQL has one endpoint per service but it internally uses multiple callers to make requests to the server based on each type of data being requested.

This is a more calculable load on normal RESTful endpoints (provided the particular request isn’t under-fetched) because all the data comes back all the time and hence there is only one roundtrip.