Search code examples
restclient-servergraphqldistributed-system

Meets GraphQL all REST requirements?

In his dissertation, Fielding defined a set of rules that should meet a REST API.

This includes among other things the following rules:

  • Client-Server
  • stateless cache Interface
  • Uniform Contract (Hypermedia or HATEOAS, ..)
  • Layered System

Is it possible to meet these requirements with GraphQL?

While the points client-server, stateless and layered-system are probably fulfilled, I am not sure about the points caching and the uniform contract.

Solution

  • Let's go through Fieldings constraints and check if GraphQL fulfills them:

    Client-Server Architecture - YES

    GraphQL is (primarily) a query language, specifying queries from a client to a server.

    Statelessness - YES

    This is dicussed in detail here. The short answer is yes, GraphQL is stateless, as there is no session concept and the server doesn't need any additional information to process a request.

    Cacheability - NO

    This one is trickier. Technically, you could cache GraphQL queries on HTTP request level (if you use HTTP). However, since clients can query arbitrary combinations of objects and properties, the hit rate of such a cache would probably be low, and the cached information highly redundant. Because of this, the GraphQL developers suggest a graph-based caching approach. Yet, this approach requires globally unique identifiers, introducing an additional constraint on top of the GraphQL specification, that suspiciously resembles the "resource identification" constraint of REST (see below).

    Another option is to defer caching to other components that provide data to the GraphQL server, but this is unrelated to GraphQL itself. Given the above, I'd say GraphQL requests are not cacheable by default.

    Layered System - YES

    Fielding described a layered architecture as one ...

    ... composed of hierarchical layers by constraining component behavior such that each component cannot “see” beyond the immediate layer with which they are interacting.

    You could set up a GraphQL server to forward requests to other GraphQL servers without the client knowing about it. In practice, GraphQL servers are often used as a "backend for the frontend", aggregating data from other services the client doesn't know about. This is a layered system.

    Interface / Uniform Contract - NO

    This constraint is often formulated through four sub-constraints:

    • Identification of resources - NO

    As mentioned above, GraphQL doesn't provide a uniform mechanism to identify resources. The GraphQL documentation states:

    HTTP is commonly associated with REST, which uses "resources" as its core concept. In contrast, GraphQL's conceptual model is an entity graph. As a result, entities in GraphQL are not identified by URLs.

    • Manipulation of resources through representations - YES(?)

    Let's assume the resources of GraphQL are the data objects, and the transferred JSON (or other format) is the representation (instead of seeing the whole GraphQL endpoint as a single resource). Then, sending a mutated JSON representation back to the server to update an object is possible.

    • Self-descriptive messages - NO(?)

    This one is, in my opinion, a matter of opinion. When is a message self-descriptive? If the goal is to be "understandable" by an arbitrarily introduced middle layer between client and server, then I'd argue GraphQL messages aren't self-descriptive. The structure of a query or mutation only makes sense in the context of a servers schema. This schema can be requested from the server, but this would extend the scope of a single message.

    • Hypermedia as the engine of application state (HATEOS) - NO

    This one is simple. GraphQL simply doesn't support the concept of links, which are the precondition and essence of hypermedia. This article has some interesting views on this topic.

    Code-On-Demand (optional) - NO

    All data that is sent from a GraphQL server to a client is typed. None of the supported types is intended to be executed. Mutation requests, which represent actions, are only sent from client to server, not the other direction. It is, of course, always possible to send code as text, but that's arguably not what GraphQL was designed for.

    To conclude, GraphQL doesn't meet all the REST requirements. And it probably wasn't intended to. It was intended to solve some problems arising from the REST principles, mainly that clients need multiple HTTP roundtrips to fetch a single object graph, and in turn receive much more data than actually used.