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
I am writing an article about traditional REST vs GraphQL
it could be interesting to see how you put in the same level two totally different things. GraphQL has nothing to do with REST in any meaningful way.