REST vs. GraphQL: A Critical Review

Deciding between using GraphQL and REST can always be a tough decision, so we’re gonna show the Pros and Cons of using each.

GraphQL

- Created by Facebook in 2012, released in 2018.
- Query language and is agnostic of the language you use.
- Deals with Resolvers.
  - One request can call many resolvers to construct a nested response.
- To differentiate a read vs. a write it uses Mutation and Query.

GraphQL Pros

- Client can model the request to contain nested entities
and custom subfields.
=> Less network data.
=> Less code in Backend to support this.
=> Makes rapid product iterations on the front-end possible, meaning client-side changes without messing around with the server.
- Avoids over-fetching.
- Avoids under-fetching.
- Prevents multiple API calls.
- Self-documenting:
  - Defines the capabilities of APIs using a strong type system.
  - Schema is displayed to the Client - Schema Definition Language (SDL). => the Frontend and Backend teams can start work in parallel because the 'contract' is established.
  - but the same thing is achieved in REST using Swagger.
  - GraphQL Faker can be used to mock data.
  
- The client has to respect the schema type or an error is thrown => Correct usage of Schema Definition Language is enforced in UI.
- Involves both the Frontend and the Backend Developers in understanding the GraphQL contract.
- Plenty of client and server libraries for GraphQL(ex. GraphQL explorer).

GraphQL Cons

- Caching:
  - supports application and endpoint caching, but network caching is not supported.
  - network caching tools like Varnish, Squid, Fastly, etc. entirely useless
  - Facebook has released DataLoader which can make GraphQL client caching easier, but clients not using NodeJS will have to port the logic, or continue to roll their own.
- Does not support versioning, so backward compatibility can be achieved only by:
  - creating new APIs.
  - implementing a mechanisms that enforces client update to latest version.
- Logic for GraphQL Mutations and Queries goes in the FE.
It means that you may end up with a client architecture that: 
  - is similar to how a Backend ORM looks(Services, Repositories, Queries).
  - has duplicated Queries/Mutations in many components and it's a Hell when you end up having many similar Queries/Mutations present in multiple components.
- To reuse code written for Queries/Mutations you may end up with components that do Over-fetching. For Queries an incomplete solution to alleviate this issue is to use GraphQL Fragments.
- Not the best solution for simple applications.
- Error handling gives you a 200 OK status code. Handled as part of the response body under a special errors object.
- JSON representation only.
- Only a single tool is used predominantly: GraphiQL

REST(Representational state transfer)

- Founded in 2010.
- Deals with Route Handlers.
  - One request calls exactly one route handler.
- To differentiate a read vs. a write it uses HTTP verbes: GET, POST, PUT, OPTION, etc.

REST Pros

- Is scalable; Architecture decouples client and server.
- Offers a great deal of flexibility.
- The Endpoint is the identity of the object.
In GraphQL the identity is separate from how you fetch it.
- Source of truth for entity stays in only 1 place.
  - this means that the entity logic is present more in BE, and there are a lot of mature tools for many programming languages that implement ORMs behind the hood.
- Server determines the shape and size of the resource.
- Caching:
  - supports application, network and endpoint caching.
  - note that network becomes useless if the endpoint caching is very customisable.
ex.
adding a selection of subfields will make the endpoint more customisable, but the network caching less efficient
GET /birds?fields=name,age
GET /birds?fields=name
are 2 different request for network cache.
- Supports versioning.
  - Which can also be a pain in the ass.
- Error handling returns the correct status code(40\*).
- Supports multiple data formats.

REST Cons

- Multiple requests to fetch related and nested entities.
  - or you have to write another api that does this.
- Over-fetching.
  - Client downloads more information than needed.
  - A workaround is to write logic which allows requests specify the required fields.
GET user?field=name,id,body
- Under-fetching.
  - Client downloads less information than needed.
- No support for nested entities; Logic has to be written for this.
- Usually the Backend developer has stronger knowledge about
the REST contract than the Frontend developer.
- To have the entities contract between Client and Backend,
you have to use Swagger.

Published at https://flawless-bits.com/blog/rest-vs-graphql

Have a Great day!