GraphQL

Table of Content

GraphQL is a powerful query language that was developed by Facebook to provide a more efficient and flexible way to query and manipulate data in APIs. Unlike traditional REST APIs, which expose a fixed set of endpoints and often require multiple round trips to the server to fetch all the necessary data, GraphQL allows the client to specify exactly what data it needs in a single request. This not only reduces the amount of data that needs to be transferred over the network, but it also allows the client to retrieve only the data that it needs, making the API more flexible and scalable.

In this blog post, we will walk through the steps for building a GraphQL API from scratch. We will start by defining the data schema, which specifies the types of data that the API will expose and the relationships between those types. Next, we will implement resolvers, which are responsible for fetching the data for each field in the schema. Then, we will create the GraphQL server, which will allow us to send queries and mutations to the API. Finally, we will test the API to ensure that it is functioning correctly.

Defining the Data Schema

The first step in building a GraphQL API is to define the data schema. This involves specifying the types of data that the API will expose and the relationships between those types. For example, if you are building an API for a to-do list application, you may have a Task type and a User type, with a one-to-many relationship between User and Task.

In GraphQL, the schema is written using the GraphQL Schema Definition Language (SDL), which is a human-readable syntax for defining the types and relationships in the schema. Here is an example of how you might define the Task and User types in the to-do list application:

type User {
  id: ID!
  name: String!
  email: String!
  tasks: [Task!]!
}

type Task {
  id: ID!
  title: String!
  description: String!
  completed: Boolean!
  user: User!
}

In this example, the User type has an id, a name, and an email, as well as a list of tasks that belong to that user. The Task type has an id, a title, a description, a completed flag, and a user who created the task.

Implementing Resolvers

Once you have defined your data schema, you will need to implement resolvers for each field in the schema. A resolver is a function that is responsible for fetching the data for a particular field. For example, if you have a Task type with a title field, you would need to implement a resolver function that fetches the title for a particular task.

In GraphQL, resolvers are typically organized into a "resolver map" where each key in the map corresponds to a field in the schema. For example, here is how you might implement the resolvers for the Task type in the to-do list application:

const resolvers = {
  Task: {
    id: (parent, args, context) => parent.id,
    title: (parent, args, context) => parent.title,
    description: (parent, args, context) => parent.description,
    completed: (parent, args, context) => parent.completed,
    user: (parent, args, context) =>
      context.users.find((user) => user.id === parent.userId),
  },
};

In this example, each resolver function takes three arguments: parent, args, and context. The parent argument is the parent object that contains the field being resolved, the args argument is an object containing any arguments passed to the field in the query, and the context argument is an object that contains shared data and helper functions that can be used by the resolvers.

In this case, the user resolver uses the context object to find the User object that is associated with the task being resolved. This allows the resolver to return the User object for the user field in the Task type.

Creating the GraphQL Server

The next step is to create the GraphQL server, which will allow us to send queries and mutations to the API. There are many libraries and frameworks available for creating a GraphQL server, such as Apollo Server and GraphQL-JS.

In this example, we will use Apollo Server, which is a popular GraphQL server implementation that supports many of the most commonly used GraphQL features. To create the server, we first need to define the schema and resolvers that we have implemented in the previous steps:

const schema = makeExecutableSchema({
  typeDefs: [UserType, TaskType],
  resolvers,
});

const server = new ApolloServer({
  schema,
  context: {
    users: [
      {
        id: "1",
        name: "Alice",
        email: "alice@example.com",
      },
      {
        id: "2",
        name: "Bob",
        email: "bob@example.com",
      },
    ],
    tasks: [
      {
        id: "1",
        title: "Learn GraphQL",
        description: "Learn how to build a GraphQL API",
        completed: true,
        userId: "1",
      },
      {
        id: "2",
        title: "Write blog post",
        description: "Write a blog post about building a GraphQL API",
        completed: false,
        userId: "1",
      },
      {
        id: "3",
        title: "Go for a run",
        description: "Go for a run to stay healthy and fit",
        completed: false,
        userId: "2",
      },
    ],
  },
});

In this example, we use the makeExecutableSchema function from the graphql-tools library to create the schema from the type definitions and resolvers that we have defined. We then create an instance of the ApolloServer class, passing in the schema and a context object that contains the data for the users and tasks in the to-do list application.

Testing the API

Once you have set up the GraphQL server, you can test the API by sending GraphQL queries and mutations to the server. This will allow you to verify that the API is functioning correctly and that the data is being returned as expected.

To send queries and mutations to the server, you can use a GraphQL client such as GraphiQL or Insomnia. These tools allow you to construct and send GraphQL queries and mutations and view the results in an easy-to-read format. For example, here is how you might query the API to fetch all the tasks for a particular user:

query {
  user(id: "1") {
    name
    email
    tasks {
      id
      title
      description
      completed
    }
  }
}

In this example, the query specifies that we want to fetch the name, email, and tasks fields for the user with the id of 1. The API will then use the user resolver to fetch the user with the specified id, and the tasks resolver to fetch the tasks for that user. The resulting data will be returned in the following format:

{
  "data": {
    "user": {
      "name": "Alice",
      "email": "alice@example.com",
      "tasks": [
        {
          "id": "1",
          "title": "Learn GraphQL",
          "description": "Learn how to build a GraphQL API",
          "completed": true
        },
        {
          "id": "2",
          "title": "Write blog post",
          "description": "Write a blog post about building a GraphQL API",
          "completed": false
        }
      ]
    }
  }
}

In addition to querying the API, you can also use GraphQL mutations to modify the data in the API. For example, here is how you might use a mutation to update the completed field for a particular task:

mutation {
  updateTask(id: "1", completed: true) {
    id
    title
    description
    completed
  }
}

In this example, the mutation specifies that we want to update the task with the id of 1, setting the completed field to true. The API will then use the appropriate resolver to update the task and return the updated data in the following format:

{
  "data": {
    "updateTask": {
      "id": "1",
      "title": "Learn GraphQL",
      "description": "Learn how to build a GraphQL API",
      "completed": true
    }
  }
}

Conclusion

In this blog post, we have walked through the steps for building a GraphQL API from scratch. We started by defining the data schema, which specifies the types of data that the API will expose and the relationships between those types. Next, we implemented resolvers, which are responsible for fetching the data for each field in the schema. Then, we created the GraphQL server, which allows us to send queries and mutations to the API. Finally, we tested the API to ensure that it is functioning correctly.

Overall, building a GraphQL API can be a time-consuming process, but it allows you to create a flexible and powerful API that can be used to build modern applications. By using GraphQL, you can reduce the amount of data transferred over the network and provide your clients with the ability to fetch only the data that they need, making your API more efficient and scalable.

As you continue to work on your GraphQL API, there are a few best practices that you should keep in mind. For example, you should always strive to keep your schema and resolvers as simple and modular as possible. This will make your code easier to understand and maintain, and it will also make it easier to add new features to your API in the future.

In addition, you should take advantage of the many tools and libraries that are available for working with GraphQL. For example, you can use the graphql-tools library to simplify the process of creating your schema and resolvers, and the apollo-server-express library to easily integrate your GraphQL server with an existing Express.js web application.

Finally, you should make sure to properly test and document your GraphQL API. This will ensure that your API is reliable and easy to use, and it will also make it easier for other developers to integrate with your API.

By following these best practices, you can build a high-quality GraphQL API that is efficient, flexible, and scalable.

Thanks for Reading 😊