GraphQL: An Introduction

Introduction

GraphQL stands for Graph Query Language and as per the official documentation is defined as "a query language for your API, and a server-side runtime for executing queries using a type system you define for your data". The official documentation further states that "it is an API standard that provides a more efficient, powerful and flexible alternative to REST (Representational State Transfer)".

In this article, we will delve into the world of GraphQL, exploring its fundamental concepts, comparing it with REST, and understanding when it's advantageous to choose GraphQL over REST. By the end, you'll have a solid understanding of GraphQL's capabilities and how it can enhance your API development experience.

What is GraphQL?

GraphQL is an open-source query language and runtime for APIs developed by Facebook. However, unlike other query languages such as SQL (Structured Query Language) which are often used to make queries to databases (such as a Postgres database) as well as other information systems, GraphQL allows clients to make requests or communicate with a server in a structured way.

What is REST

REST is a software architectural style for sharing data between different systems. It is often used to create REST APIs (Application Programming Interfaces) that follow the principles of REST which are a set of rules that define how resources are identified, accessed, and manipulated. These principles include Stateless Communication, Uniform Interfaces, Client-Server Separation and Cacheability.

GraphQL vs REST

There are advantages and disadvantages to using both GraphQL and REST and even though they both solve similar problems i.e. communication between systems, they go about it in different ways. The major difference is in their architecture as well as the way requests are made.

When requesting data from a REST server, the client requests the data it needs from a specific endpoint for example if you were building a blogging platform that allowed users to create profiles and write blogs. If a user needed to view his/her profile, a GET request would be made to a specific endpoint such as localhost:5000/api/v1/profile/:profileId. However, if that user needed to make a request to get every blog he or she had ever written, the user would make a GET request to another endpoint such as localhost:5000/api/v1/blog/:profileId.

In GraphQL on the other hand, a client requests or queries the server for any data it needs from a single endpoint. This allows the client to precisely specify the data it needs and receive it in a single request there mitigating the issues of over-fetching or under-fetching data that often occur with REST APIs.

Important Concepts in GraphQL

• GraphQL Schemas: At the core of GraphQL lies the schema. It can be said to be the blueprint for communication between the client and the server. It specifies the data types, queries the client can make, the type of mutations the client can make, and the relationship between types. GraphQL schemas provide clear documentation which reduces errors that occur as a result of mismatched data between client and server. Below are examples of GraphQL schema types, queries, and mutations.

type Author {
  id: ID!
  name: String!
  email: String!
  blogs: [Blog!]!
}

type Blog {
  id: ID!
  title: String!
  content: String!
  author: Author!
}


type Query {
  blogs: [Blog!]!
  blog(id: ID!): Blog
  authors: [Author!]!
  author(id: ID!): Author
}

type Mutation {
  createBlog(title: String!, content: String!, authorId: ID!): Blog!
  updateBlog(id: ID!, title: String, content: String): Blog!
  deleteBlog(id: ID!): Boolean!
  createAuthor(name: String!, email: String!): Author!
  updateAuthor(id: ID!, name: String, email: String): Author!
  deleteAuthor(id: ID!): Boolean!
}

• GraphQL Queries: A query is a GraphQL operation that allows a client to request data from a GraphQL server. It can be thought of as a GET request. Queries are well structured in a hierarchical model that allows the client the flexibility to specify the exact data it needs thereby eliminating the need for fixed endpoints as is the case in REST APIs. Below are examples of GraphQL queries.

- Fetch all blogs with the author's name and id
query {
  blogs {
    id
    title
    content
    author {
      id
      name
    }
  }
}

- Fetch a single blog with the author's id and name by blog id
query {
  blog(id: "123") {
    id
    title
    content
    author {
      id
      name
    }
  }
}

• GraphQL Mutations: While queries are used to fetch data from the server, mutations on the other hand are used to create or modify data on the server. It allows the client to specify the exact data it wants to change. Mutations can be thought of as POST, PUT, PATCH, and DELETE requests which are used in REST APIs. Below are examples of GraphQL mutations.

- Create blog
mutation {
  createBlog(title: "New Blog", content: "This is the content.", authorId: "456") {
    id
    title
    content
    author {
      id
      name
    }
  }
}
- Create author
mutation {
  createAuthor(name: "John Doe", email: "[e-mail]") {
    id
    name
    email
  }
}

When to use GraphQL

The choice between GraphQL and REST depends on various factors and even though most developers if given the choice would still choose REST, there are times when GraphQL could be the better option.

• In cases where you would want the client to control the exact amount of data it needs to avoid over-fetching and under-fetching of data, GraphQL could be the better option.
• Using GraphQL alleviates bandwidth concerns as small devices such as smartwatches and mobile phones cannot handle large amounts of data. In such cases, GraphQL's ability to allow the client to specify the data it requires might make it a better option.
• GraphQL can optimize the performance of a server by reducing the number of network requests required to get required data as all required data can be gotten in one network request.

Conclusion

In this article, we've explored the fundamentals of GraphQL and compared it with the traditional REST approach. GraphQL provides a more efficient, flexible, and client-centric way of communicating with APIs. By allowing clients to request only the necessary data, GraphQL mitigates issues like over-fetching and under-fetching, leading to optimized network usage and improved performance.

To learn how to implement GraphQL APIs using express, click here.