Introduction to GraphQL

GraphQL is a query language for your API, and a server-side runtime for executing queries by using a type system you define for your data. GraphQL isn't tied to any specific database or storage engine and is instead backed by your existing code and data.

A GraphQL service is created by defining types and fields on those types, then providing functions for each field on each type. For example, a GraphQL service that tells us who the logged in user is (me) as well as that user's name might look something like this:

type Query {
  me: User
}

type User {
  id: ID
  name: String
}

Along with functions for each field on each type:

function Query_me(request) {
  return request.auth.user;
}

function User_name(user) {
  return user.getName();
}

Once a GraphQL service is running (typically at a URL on a web service), it can be sent GraphQL queries to validate and execute. A received query is first checked to ensure it only refers to the types and fields defined, then runs the provided functions to produce a result.

For example the query:

{
  me {
    name
  }
}

Could produce the JSON result:

{
  "me": {
    "name": "Luke Skywalker"
  }
}

Learn more about GraphQL—the query language, type system, how the GraphQL service works, as well as best practices for using GraphQL to solve common problems—in the articles written in this section.

ADVANTAGES OF GRAPHQL

GraphQL offers many benefits over REST APIs. One of the main benefits is clients have the ability to dictate exactly what they need from the server, and receive that data in a predictable way.

For example, imagine you have the following schema:

type Query {
  me: User
}

type User {
  id: ID
  name: String
  city: String
  state: String
  friends: [User]
}


Copy

Now let’s say that you just needed to get a User‘s name. If you had a REST API, you would typically receive the entire User object back in your response. This leads to overfetching and can result in performance issues. With GraphQL, you only receive the data you explicitly request.

Here’s what our User name query would look like:

{
  me {
    name
  }
}


Copy

And here’s what our response would look like:

{
  "me": {
    "name": "John Doe"
  }
}


Copy

Another big benefit is the ability to retrieve many resources in a single request. Continuing with our example schema, imagine we want to also fetch the names of our User‘s friends as well. For a traditional REST API, we would probably need to make an additional request to a /friends?id=X endpoint, passing in our User‘s ID.

We can simply append our friends property to our query and receive all our names in a single request:

{
  me {
    name
    friends {
        name
    }
  }
}


Copy

And here’s what our response would look like:

{
  "me": {
    "name": "John Doe"
    "friends": [
        {
            "name": "Jane Doe"
        },
        {
            "name": "Jim Doe"
        }
    ]
  }
}


Copy

Another benefit is that it is strongly-typed which allows API consumers to know exactly what data is available, and in what form it exists. According to the docs: “Every GraphQL service defines a set of types which completely describe the set of possible data you can query on that service. Then, when queries come in, they are validated and executed against that schema.”

DISADVANTAGES OF GRAPHQL

While GraphQL has many advantages over traditional REST APIs, there are several key disadvantages as well.

One disadvantage is queries always return a HTTP status code of 200, regardless of whether or not that query was successful. If your query is unsuccessful, your response JSON will have a top-level errors key with associated error messages and stacktrace. This can make it much more difficult to do error handling and can lead to additional complexity for things like monitoring.

Another disadvantage is the lack of built-in caching support. Because REST APIs have multiple endpoints, they can leverage native HTTP caching to avoid refetching resources. With GraphQL, you will need to setup your own caching support which means relying on another library, or setting up something like globally unique IDs for your backend.

This leads us to the final disadvantage: complexity. If you have a simple REST API and deal with data that is relatively consistent over time, you would be better off sticking with your REST API. For companies that deal with rapidly-changing data, and have the engineering resources to devote to rearchitecting their API platforms, GraphQL can solve many of the pain points experienced with REST APIs.

GraphQL provides an interesting solution to common hurdles faced when using REST APIs. While using GraphQL has several downsides, if you find yourself working with rapidly-changing data at scale, it could be a great solution for your business. To learn more about, check out the docs. And if you’re looking for a more fully-fledged GraphQL solution, Apollo provides an easy way to get started on both the client and server-side.

Tutorial Ref: https://www.tutorialspoint.com/graphql/graphql_tutorial.pdf