What is a Mutation in GraphQL?

In GraphQL, a mutation is a type of operation that allows clients to modify data on the server. This includes creating, updating, or deleting records. Unlike queries, which are used to fetch data, mutations are designed to change the state of the data and can also return the modified data in the response.

Key Features of GraphQL Mutations

• State Changes: Mutations are used to perform operations that change the state of the data, such as adding new records or updating existing ones.
• Return Values: Mutations can return the modified data, allowing clients to immediately see the results of their changes.
• Strongly Typed: Like queries, mutations are strongly typed and validated against the schema, ensuring that only valid operations are executed.
• Single Endpoint: All mutations are typically sent to a single endpoint, making it easy to manage and organize API operations.

Basic Structure of a Mutation

A GraphQL mutation starts with the mutation keyword, followed by the operation you want to perform. Here’s a simple example of a mutation to create a new user:

mutation {
    createUser (name: "Alice", email: "alice@example.com") {
        id
        name
        email
    }
}

Sample Mutation Explained

In the example above, the mutation createUser is called with the arguments name and email. The mutation requests the id, name, and email fields of the newly created user in the response.

Sample Response

The server's response to the above mutation might look like this:

{
    "data": {
        "createUser ": {
            "id": "1",
            "name": "Alice",
            "email": "alice@example.com"
        }
    }
}

Updating Data with Mutations

Mutations can also be used to update existing records. For example, to update a user's email, you might use the following mutation:

mutation {
    updateUser (id: "1", email: "alice.new@example.com") {
        id
        name
        email
    }
}

Sample Update Response

The server's response to the update mutation might look like this:

{
    "data": {
        "updateUser ": {
            "id": "1",
            "name": "Alice",
            "email": "alice.new@example.com"
        }
    }
}

Deleting Data with Mutations

Mutations can also be used to delete records. For example, to delete a user, you might use the following mutation:

mutation {
    deleteUser (id: "1") {
        id
        name
    }
}

Sample Delete Response

The server's response to the delete mutation might look like this:

{
    "data": {
        "deleteUser ": {
            "id": "1",
            "name": "Alice"
        }
    }
}

Using Input Types in Mutations

To make mutations more organized, you can use input types to define the structure of the data being sent. For example:

input UserInput {
    name: String!
    email: String!
}

type Mutation {
    createUser (input: UserInput!): User
}

Sample Mutation with Input Type

The mutation can then be called like this:

mutation {
    createUser (input: { name: "Alice", email: "alice@example.com" }) {
        id
        name
        email
    }
}

Conclusion

Mutations in GraphQL are essential for modifying data on the server. They provide a structured way to create, update, and delete records while allowing clients to specify the exact data they want in return. By using mutations, developers can efficiently manage data changes and ensure that their applications remain responsive and up-to-date. Understanding how to construct and utilize mutations is crucial for effectively working with GraphQL APIs.