Home Technology Introduction to GraphQL

Introduction to GraphQL

by jugaljoshi

Why GraphQL exits? “Why do I care about a new API design trend? REST is… fine.”

The benefits of bringing new technology has to be weighed against its costs. There are lots of things to measure.

  • Time taken to learn.
  • Time taken to develop features and revamp
  • Overhead of maintaining two systems

With such high costs, any new tech has to be better, faster and more productive. Incremental improvements, while exciting, just aren’t worth the investment. The types of APIs we are going to talk about, GraphQL in particular; are in my opinion a huge step forward and deliver more than enough benefit to justify the cost.

“There is no such thing as a new idea. It is impossible. We simply take a lot of old ideas and put them into a sort of mental kaleidoscope. We give them a turn and they make new and curious combinations.”

— Mark Twain in “Mark Twain’s Own Autobiography: The Chapters From The North American Review”

Problems with RESTful:

  • Multiple endpoints (Multiple round trips)
  • Over-fetching/Under-fetching data
  • API versioning
  • Weak typing
  • Client kept in the dark

What is GraphQL?

GraphQL is a query language for APIs and runtime for fulfilling those queries with your existing data. GraphQL provides a complete and understandable description of the data in your API, gives clients the power to ask for exactly what they need and nothing more, makes it easier to evolve APIs over time, and enables powerful development.

How it all works:

Let’s say, we have three tables USER, COMPANY and POSITION in our database, with relation defined as:

Figure-1 Relation between user, company and position tables

Let’s create a graph to get data using user id. Assuming that there is no restrictions on fetching data of any kind for a given client. Hence in graph this data and table relationship will look like this:

Figure-2 Graph representation of different objects

Every table/object in the above graph can be represented by a Schema. Where Schema (in GraphQL) defines datatypes, the relationship between different objects. Lets create a schema for User, Company, Position and their relationships.

User: {
        id: {type: new GraphQLNonNull(GraphQLInt)},
        first_name: {type: GraphQLString},
        last_name: {type: GraphQLString},
        company: {type: new Company},
        position:{type: new Position},
Company: {
   id: {type: new GraphQLNonNull(GraphQLInt)},
   name: {type: GraphQLString},
   description: {type: GraphQLString}

Company: {
   id: {type: new GraphQLNonNull(GraphQLInt)},
   name: {type: GraphQLString},
   description: {type: GraphQLString}

Above schema defines User data where id is not nullable integer field, Company and Position, which are linked to User table.

How to query:

Every Schema is attached to a RootQuery, which defines a queries return type, arguments and how to resolve (act upon a query). RootQuery is the entry point for all requests.

Figure-3 RootQuery handling and fetching data for a User

Above RootQuery takes user id as input argument, return type is a User object (defined in schema).

const RootQueryUser = new GraphQLObjectType({
    name: 'UserQuery',
    description: "User Application Schema Root",
    fields: () => ({
        getUser: {
            type: User, //user schema defined above, return type
            description: "Return a User Object",
            args: {
                id: {type: new GraphQLNonNull(GraphQLInt)}, // query argument
            resolve: async (parentResult, args, context, info) => {
               //application logic

const UserAppSchema = new GraphQLSchema({
  query: RootQueryUser

Request flow:

  1. A client makes a call with graph query.
  2. Graph Server checks if this is a graph query or not; based on routes.
  3. RootQuery executes resolve function with arguments, context(if any) and graph query info object.
  4. Resolve function executes application logic, validates and filters JSON data according to Schema.
  5. Graph API converts this response to return type (ie: User schema)
  6. Response is sent back to the client.
Figure-4 Basic request flow for a client

Client Query and Response:

Figure-5 Detailed request response view

You may also like

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: