Enumeration Types in GraphQL Schema

In the area of GraphQL schema design, enumeration types play an important role in defining a structured set of values for specific fields. Enumerations serve as a means to restrict the possible options for a field, ensuring data consistency and clarity throughout an API. In this article, we will explore the concept of enumeration types in GraphQL with their importance through practical examples and use cases.

What are Enumeration Types in GraphQL?

Enumeration types referred to as enums, are a valuable feature in GraphQL schemas. An enum is a schema in GraphQL that represents a predefined list of possible values. It allows developers to define a specific set of values that a field can have. Enums are useful when a field should only have a limited number of possible values, such as status fields (for examples: “PENDING“, “IN_PROGRESS“, “COMPLETED“) or type fields (for examples: “USER“, “ADMIN“, “GUEST“).

enum OrderStatus {
  PENDING
  SHIPPED
  DELIVERED
  CANCELLED
}

In this example, OrderStatus is an enum type with four possible values: PENDING, SHIPPED, DELIVERED, and CANCELLED.

How to Use Enumeration Types

Thus, we can create an enumeration type in GraphQL by enumerating all the possibilities we wish to permit for a given field. For instance, we may see choices like To Do, In Progress, or Done for a task’s state. Once the “enum” keyword has been used, we place these options inside curly braces.

Here’s how we set up an enumeration type in GraphQL:

enum TaskStatus {
  TODO
  IN_PROGRESS
  DONE
}

Explanation: We can list out all the options we want to allow for a field, like the status of a task, inside curly braces after using the “enum” keyword.

Integrating Enum Types

We can utilize our defined enum type for various fields in our GraphQL schema. Suppose we want to monitor the status of every task that belongs to the “Task” type in our schema. The “status” field would be created, and we would specify that it could only contain one of the values we listed in our TaskStatus enum.

Now, let’s use our enum type in a GraphQL schema. Say we have a “Task” type:

type Task {
  id: ID!
  title: String!
  description: String!
  status: TaskStatus!
}

Explanation: The “status” field uses our TaskStatus enum type. This means the status of a task can only be one of the options we defined.

Querying with Enums

Now, we may include a task’s status in our query when we want to know more about it. When GraphQL displays a status, it will ensure that it corresponds with one of the options we have configured in our enum. Thus, we don’t need to be concerned about receiving strange or unexpected data back.

When we want to get information about a task, we can include its status in our query:

query {
  task(id: "123") {
    id
    title
    status
  }
}

Explanation: GraphQL will make sure that the status it gives we matches one of the options we have set up in our enum. No surprises!

Integrating Enumeration Types in Fields

To integrate enumeration types into GraphQL schemas, developers define the enum using the enum keyword followed by the enum’s name and its possible values within curly braces. For instance, defining an enum for order status might include values like PENDING, SHIPPED, DELIVERED, and CANCELLED.

type Task {
  id: ID!
  title: String!
  description: String!
  status: TaskStatus!
}

enum TaskStatus {
  TODO
  IN_PROGRESS
  DONE
}

Explanation: Here, we define a Task type with fields id, title, description, and status. The status field uses the TaskStatus enum type, which defines three possible values: TODO, IN_PROGRESS, and DONE. This ensures that the status of a task can only be one of these predefined values.

Querying Enumeration Fields

Once enumeration types are integrated into the schema, they can be used as field types within other types. For example, in a schema for managing tasks, an enum type TaskStatus might include values such as TODO, IN_PROGRESS, and DONE. These values can then be used as the type for a field representing the status of a task within the Task type.

query {
  task(id: "123") {
    id
    title
    status
  }
}

Explanation: In this query, we retrieve information about a task with ID “123“, including its id, title, and status. Since status is an enum field, it will return one of the predefined values (TODO, IN_PROGRESS, or DONE).

Why Use Enum Types?

Enum types make our GraphQL API easier to understand and use. They keep things organized and prevent mistakes by limiting the choices users can make. This way, everyone knows what to expect, which is super important when we’re dealing with lots of data and different parts of an app.

Enum Resolvers

In GraphQL implementations, resolvers are functions responsible for fetching the data for a field. While enumeration types themselves do not typically require resolvers, in some cases, custom logic may be necessary to handle how enum values are resolved or processed.

While enums themselves typically don’t require resolvers, custom logic may be needed in certain scenarios. For example, if we want to format the enum values differently when they’re returned in a response, we could use a resolver to handle that logic. However, the resolver would depend on the GraphQL implementation we’re using (e.g., Apollo Server, GraphQL.js) and the specific requirements of our application.

Example

Consider a scenario where we are developing a GraphQL API for managing tasks. We want to define a type for the status of a task, which can be either “To Do,” “In Progress,” or “Done.”

enum TaskStatus {
  TODO
  IN_PROGRESS
  DONE
}

type Task {
  id: ID!
  title: String!
  description: String!
  status: TaskStatus!
}

Explanation: In this example, we’ve declared an enum type TaskStatus with three possible values: TODO, IN_PROGRESS, and DONE. The Task type includes a field status of type TaskStatus, indicating the status of the task.

Now, let’s query for a task and specify the desired status:

query {
  task(id: "123") {
    id
    title
    status
  }
}

Conclusion

Enumeration types in GraphQL offer a powerful way to define a fixed set of values for fields ensuring data integrity and clarity in API interactions. By using enumeration types developers can easily restrict the possible values that can be assigned to a field, making the API easier to understand and use. It enumeration types play a important role in enhancing the readability, predictability and maintainability of GraphQL APIs.

Article Tags :

GraphQL