Is GraphQL REST compliant (almost)?

Question

I am writing an article about traditional REST vs GraphQL.

However, after doing some research about REST (not just a specific implementation of REST), I started to see that GraphQL actually abides to the same rules as REST, with 1 minor exception.

IMPORTANT: I am talking about the actual REST specification. I am not just talking about a traditional implementation of REST.

REST principles are described here:

• https://en.wikipedia.org/wiki/Representational_state_transfer#Architectural_constraints
• https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_2
• https://ninenines.eu/docs/en/cowboy/2.0/guide/rest_principles/

These are:

• Client Server Architecture
• Statelessness
• Cacheability
• Layered system
• Uniform interface
  • Resource identification in requests
  • Resource manipulation through representations
  • Self-descriptive messages
  • Hypermedia as the engine of application state (HATEOAS)

GraphQL trivially satisfies the criteria of "Client Server Architecture", "Statelessness" and "Layered System".

A GraphQL implementation can be made to satisfy cacheability, by enforcing that id is required for every resource (see: https://graphql.org/learn/caching/)

Which leaves "Uniform Interface", which has 4 sub-constraints:

Resource identification in requests

Individual resources are identified in requests.

GraphQL satisfies Resource identification in requests, as there is no mention that the resources must be in the URL or the usage of HTTP verbs.

Therefore both:

GET /books?fields=title

and

POST /graphQL
{
    books {
        id
        title
    }
}

are REST compliant.

Resource manipulation through representations

When a client holds a representation of a resource, including any metadata attached, it has enough information to modify or delete the resource.

GraphQL can satisfy this, provided the resource identifier attribute is included for every request. i.e. the following would be invalid:

{
    books {
        title
        author: {
            name
        }
    }
}

but the following is valid:

{
    books {
        id
        title
        author: {
            id
            name
        }
    }
}  

Although I would argue that a good API should not return data that we don't need. The client should choose if they want the ID or not, but I digress.

Self-descriptive messages

Each message includes enough information to describe how to process the message. For example, which parser to invoke can be specified by a media type.

GraphQL satisfies this as the data returned is JSON, and the media type is application/json.

Hypermedia as the engine of application state (HATEOAS)

Having accessed an initial URI for the REST application—analogous to a human Web user accessing the home page of a website—a REST client should then be able to use server-provided links dynamically to discover all the available actions and resources it needs. As access proceeds, the server responds with text that includes hyperlinks to other actions that are currently available. There is no need for the client to be hard-coded with information regarding the structure or dynamics of the application.

GraphQL doesn't satisfy HATEOAS perfectly, but nor do many other real API's that claim to be RESTful.

This criteria is also pointless when using GraphQL, because everything is done on a single URI.

However, it is worth noting that GraphQL also has a feature called Introspection, which allows the client to get information about what queries the server supports and the documentation, which in a way is more helpful than just a URI.

Conclusion

So to conclude, it seems that GraphQL satisfies:

• Client Server Architecture
• Statelessness
• Layered system
• Resource identification in requests
• Self-descriptive messages

By enforcing that id is required for every resource, it can also be made to support:

• Cacheability
• Resource manipulation through representations

And doesn't really need to support:

• Hypermedia as the engine of application state (HATEOAS), because everything is done on one URL, and GraphQL has introspection.

Therefore can we conclude that GraphQL satisfies REST, with the exception of HATEOAS (which IMO is the worst part of REST anyway).

Am I correct, or have I misunderstood the REST spec.

https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_2

Answer 1

No, GraphQL is not RESTful in any meaningful way.

Yes, when viewed in isolation it certainly is possible to develop a RESTful architecture that makes use of GraphQL. And in principle, GraphQL is already cacheable even when not introducing any IDs.

But as normally used, GraphQL is not RESTful.

• In particular, GraphQL-over-HTTP certainly does not use HTTP in a RESTful way whereas “normal” RESTful APIs are nothing more than HTTP used in a specific style.

• One interesting difference is that a GraphQL query may touch multiple resources/objects in one query. This doesn't make caching impossible, just very hard. For example, you cannot leverage HTTP caching but have to roll your own.

• GraphQL doesn't even have a clear concept of a resource. Instead, you have an object graph. It is not always possible to tell where one object ends and another starts, unless we use simplistic definitions that are based on JSON objects or GraphQL's type system. Instead we might say: in GraphQL, the graph is the only resource.

• GraphQL subscriptions break with the typical 1:1 query:response pattern. It could be argued that this clashes with REST's statelessness principle since the subscriber will be notified when the server's state changes. In particular, the presence of a subscription is shared state.

In summary, I'd say that GraphQL is about as RESTful as any other Web-based API: probably not RESTful by default, but can be used in that style if explicitly designed that way (possibly avoiding certain features).