Why GraphQL is the new REST

Today most web services that I interact with in my work as a developer follow the REST standard (as close as they can). All is usually fine interacting with a REST service as long as there is proper documentation available. Usually working for enterprise client however you will be happy if you receive it in a PDF-file within days of starting to integrate the service...

After getting your hands on a reasonably fresh copy of the documentation you are free to POST, PUT, GET and DELETE away as long as the service is functional.

So - what is the problem I have with REST you might think?

I asked a GraphQL worshipping senior developer on one of my first consulting gigs what advantages it has over REST. My brain was going something like: REST works, REST is widely used, REST is simple, there are many tools that support and... well it's not SOAP at least. His response was something along the lines of "everything". I usually avoid listening to someone who is that uncompromising about something so I figured I would at least investigate it when I had the time.

A few months passed and a new side project idea dawned on me (as they do a couple of times a year). I was going to build a mock API tool. It was going to be great. It was going to be GraphQL.

So as I set out to build something with this magical new tool the truth slowly dawned on me. This is what is going to replace REST. Okay let's not wait any further here is why:

1. Fetch related data on demand

GraphQL enables you to fetch the related data you want in only one HTTP call. Let's say you have a movie database API and want to fetch the movie and the actors in the movie. In REST that might look something like:

GET /movies/star-wars
and then
GET /movies/star-wars/actors

Two HTTP calls => more overhead.

In GraphQL you would execute something like the following query:

{

  getMovie(id: "star-wars") {
    releaseDate
    name
    actors {
      name
    }
  }
}

A single HTTP call. Possibility to fetch related data as many levels down as you want.

2. Automated documentation

As mentioned before documentation is in my opinion key to interacting successfully with a REST API. What is the path? Which method? What query parameters can i pass in? How should the body look like? What headers should I pass?

Of course there are tools that make beautiful documentation for REST APIs that makes this very clear. However it takes work for developers to create that type of beautiful documentation. Time that many of us do not have. That is the way you end up with a PDF file sent a couple days to late over email.

In GraphQL you will get automated documentation that you can use to explore and experiment with the API through a GUI such as GraphiQL which you can check out here.

3. Built in validation and type checking

In a REST API you will have to choose a library to handle your input validation. Or worse yet invent your own. In GraphQL you define your schema and types and both the server and client side validation is handled for you. This is an example of a type:

type Movie {
  name: String!

}

The name property is of type String and hence the ! it is required. This means the server will stop incoming requests which does not contain a name and that consuming clients will stop outgoing requests. Neat.

4. Effective caching

Using libraries such as Apollo on the frontend there is built in smart caching mechanisms that make sure you do not fetch anything unless it has been updated. Let's say you log in to your application and thereby fetch the user logging in in an API call. Instead of re-fetching the user from the API on each page reload Apollo will cache the user until you update it, for example change the email address.

5. It keeps evolving

GraphQL is a growing ecosystem and the community around it is great. It is still young and will keep improving over the coming years.

Conclusion

These are the top five reasons I think GraphQL wins over REST. However as I mentioned I avoid listening to people who see the world in black or white so I still don't think it might be worth it starting to rip out REST at every place you see it from now on. I do think however that you should give GraphQL a try and maybe some day you will find the perfect use case for it.

Let me know if you have a GraphQL project that you want to share!