Welcome to post #3 in my GraphQL series!

During the everis innovation session mentioned in post #1, we covered some of the cons of RESTful APIs. It’s worth refreshing your memory here and here.

The 5 most relevant pain points are:

  • Only an interface; no help on backend API implementation
  • Perfectly suited for CRUD operations, but becomes awkward for non-CRUD
  • Verbose when requesting several resources, implying N+1 calls to different endpoints, which ends up downgrading client performance
  • Self-explanatory for verbs like GET or DELETE, but less clear for other HTTP verbs like POST, PUT or PATCH
  • Customisations and versioning usually imply endpoint duplication and implementation of complex if-statements on the server.

But how can GraphQL provide solutions for these concerns?

  • GraphQL offers a server-side engine that automatically parses and responds to the client’s queries
  • GraphQL is not CRUD-orientated, but query-orientated. Thus, it is better suited for complex queries, while also covering creations, updates and deletions through its concept of “mutations
  • It optimizes performance and is as least verbose as possible. It responds with JSON objects with no more than what the client has asked for and if the request includes nested entities, those will be retrieved in the same response. Of course, the GraphQL engine may need to perform several requests to backend datasources, but will still minimise the number of bits being transferred through the wire back to the client, highly improving client performance and reducing verbosity.
  • No more loosely defined HTTP verbs. The GraphQL approach is query or operation-orientated. The good news: an “update” will be again an “update”, not a “POST” anymore!
  • We cannot tell if a REST field is actually being used by clients, but GraphQL offers field monitoring to know when there are no more clients using it anymore. This allows immediate deprecation. Evolution through versioning is still the way to go for new features, but now we have out-of-the-box traceability of what our clients actually use.

Let’s have a look at some examples.

There are several sandboxes out there for us to try GraphQL and see what it’s all about.

During the everis innovation session, we played with GraphiQL (an IDE for testing GraphQL) together with SWAPI (an API around Star Wards universe), which turned out to be really developer friendly, straightforward and fun!

Graph-i-QL and SWAPI demo:

Observable metadata schema, with code-completion in the IDE:

Schema definition on server-side, using NodeJS/Express:

Named queries in GraphQL:

Mutations in GraphQL:

In my next post I’ll finally delve into: GraphQL – too good to be true?, and when we believe GraphQL can actually fit better than REST as integration style.

Stay tuned!