GraphQL Vs REST & Introduction to GraphQL

Posted on by pulgupta

We all have created numerous REST services so much so that eventually REST has become a de facto standard for creating web based API and surely they have served the purpose really well.

However with changing technological needs we have encountered multiple situations where REST seems limiting. Things like versioning and supporting multiple kind of clients forces us to upgrade our API carefully as that might break our consumers.

As always “Necessity is the mother of all invention” and in case of Web API the same things happened  when developers created things like GraphQL and gRPC.

Today we will look into GraphQL and try to understand how we can leverage this new way of creating API to solve all the things which require considerable amount of effort in the RESTful way of working.

GraphQL is a very vast subject and I will not be covering everything in a single blog. This blog is the first part of a series of blogs which I am planning to write on GraphQL covering things like queries, mutations, fragments and directives in detail. But for now lets try to understand the basics of GraphQL.

Fundamental difference between the two approaches

  1. REST: [Architectural Pattern] vs GraphQL: [Specification]
    1. REST is a pattern which tells us how we should be creating our API. REST in no way enforces anything and this is one of the worst drawback of a REST based system as a developer can do virtually anything with a REST API without actually breaking anything.
    2. On the other hand GraphQL is a well defined specification which strictly dictates the terms and conditions of a API. This helps us in keeping the system well defined in the long run.
  2. REST: [Server Driven] vs GraphQL: [Client Driven]
    1. REST is server driven which means it is the server which dictates  what will be returned to the client.
    2. In GraphQL we provide query capabilities to the client and a client then can pick and choose what data it needs. Client can then also alter the query to add and remove the amount of data returned.

These differences are on a very high level. As we dig deeper we will see many things which makes these two approaches completely different. For now just try to understand the concept behind GraphQL. I will be coming up with codes and demos to actually show what I means in each of the section.

Lets see more set of differences between the two approaches

  1. No need of RESTful resources, HTTP verbs or HTTP Status codes
    1. GraphQL does not need to use HTTP verbs like GET, PUT, POST to specify the behaviour of the API. Everything is a POST in GraphQL even a GET! Also GraphQL has moved away from HTTP status codes to highlight different error or success scenarios. GraphQL exposes just one endpoint which is used of everything.
  2. Supporting Dynamic responses for different clients
    1. In REST our model/DTO classes define what we are sending to the client. In GraphQL, client can send in a query and it will get only what he has asked for.
  3. Query & Mutation separation
    1. In GraphQL we have
      1. Query: A way to fetch data
      2. Mutation: A way to update data
  4. Limiting the use of DTOs and model mappers
    1. This is something which I have observed from my experience. In a REST based system where we are consuming a backend service we create DTOs which decide the API contract. These DTO’s are generally a subset of our entity models as we do not want to send everything to the client as it will not be using every field. However in case of GraphQL we can use the models directly for our API contract as in case of GraphQL client can itself filter out the data which it is not using. Hence we do not need an over head of maintaining DTOs and then using model mappers to map data from a entity model object to a DTO object. This might be confuse you but keep it in your mind and we will surely see an example just for this case.
  5. Alias allows client to rename elements
    1. In a GraphQL system I can create aliases for my data elements on runtime. This means if say I have a field “customerId” in my User object, my client can refer to it as “applicantId” on runtime. This essentially means that now my fields can have different names for different client thus ending a never ending fight on naming conventions.
  6. Standardized support for push
    1. GraphQL specification provide details how to implement push mechanisms. Hence earlier things which needed a client to keep polling the server can now be developed using push from the server side whenever data is available. This is till web sockets under the hood but with GraphQL specification everything just got well defined and well-articulated.

Sample GraphQL Query

GraphQL: POST https://your-api/pizza 
{
    query {
        pizza {
            base: bread // Example of an Alias
            sauce
            cheese
            toppings
        }
    }
}

From all the above changes we can clearly conclude that GraphQL has a lot of options and features which help a server to adapt to the ever increasing list of consumers. Even if we have tiny list of consumers still GraphQL shines as it is well defined and specification helps to keep things standardised.

Also if by now you are thinking that this looks like a SOAP API you are somewhat correct. For me best parts of SOAP and REST are combined into GraphQL and thus I would recommend every developer to understand the basics of GraphQL and evaluate if it can solve your issues in anything which was build using REST.

This completes the introduction part. I will not come up with a small demo and will be covering things like Queries, Mutations. It will help you to actually see the things we have discussed till now.

In case you feel you have not understood anything please feel free to contact me through various channels listed on this blog.

Leave a comment