The Mutation API is your Secret Weapon!

The Mutation API allows for you to alter your existing data by creating, updating and deleting.

Illustration of API

What is a Mutation API?

The GraphCMS API is, at the core, built from content models. Content Models are custom GraphQL Types comprised of one or more fields. The Mutation API modifies your content and content models directly. Let's use an example of a blog to see how mutations work in practice. If you’re looking for a deeper explanation, you can find it here in the docs. Beware that the Mutation API is an advanced feature and should be used with caution, ideally on a staged branch before moving to production. If you have any questions, hop into our slack group!

There are 3 Main Types of Mutations:

Simple Mutations

Create, Update, Upsert and Delete single nodes of your data types. Example: Create, update, or delete a blog post.

Batch Mutations

Update and Delete multiple nodes of your data in one go. Example: Change a batch of posts from Draft to Published.

Relation Mutations

Create, Update, Upsert and Delete single nodes of a certain object type. Example: Associate a batch of posts with a new Author.

  mutation {
    createBlogPost(
      data: {
        authorName: "Jane Smith"
        title: "The Pros and Woes of a Serverless Backend"
        coverImage: "serverless_illustration.png"
        createdAt: "28-12-2018 17:54"
        slug: "serverless-backend" })
        {
          id
          title
          createdAt
          slug
        }
      }

Creating Content - Publishing Has Never Been Faster

Creating content is one of the most commonly used mutations. You can create all the necessary information pertaining to the Blog Post in one action. Make sure to fill in all REQUIRED fields with appropriate data. In this scenario, we are creating a newBlogPost for our blog. Using the management API for importing legacy data is a dream!

Updating Content!

Another great feature of a Headless CMS is the ease in updating content. The ability to update content is specific to existing data points using the where argument. In this example, we are updating the post slug for SEO optimization.

  mutation {
    updateBlogPost(
      data: {
        authorName: "Jane Smith"
        title: "The Pros and Woes of a Serverless Backend"
        coverImage: "serverless_illustration.png"
        createdAt: "28-12-2018 17:54"
        slug: "serverless-backend"
      }
      where: {
        slug: "pros-and-cons-serverless-backend"
    }) {
      id
      title
      createdAt
      slug
    }
  }
  mutation {
    upsertBlogPost(
      where: {
        email: "author.name@example.com"
      }
      create: {
        email:
          "author.name@example.com"
        authorName: "Jane Smith"
        title: "The Pros and Woes of a Serverless Backend"
        coverImage: "serverless_illustration.png"
        createdAt: "28-12-2018 17:54"
        slug: "serverless-backend"
      }
      update: {
        coverImage: "decentralized.png"
      }
    ) {
      id
      title
      createdAt
      slug
    }
  }

Upserting Content - Update if it exists, Create if it doesn't!

When we want to either update existing content or create new content in a single mutation, we can upsert our content. In this instance, I am searching if anyone on the team has added Jane's email to her blog post if not, I will create it.

Delete Content Without a Hassle

Deleting content seems simple enough, and it is with the right set of mutation tools by GraphCMS. Here we are deleting an entire blog post by locating it with it's title. You can also select a content entry using other fields such as a slug or some arbitrary ID.

  mutation {
    deleteBlogPost(where: {
      title: "The Pros and Woes of a Serverless Backend"
    }) {
      id
      title
      createdAt
      slug
    }
  }

Change Nested Content for a Ripple Effect - Advanced Feature

nested content illustration

Nested mutations allow for related content to be created and updated in a partially ordered sequence of activities which is executed in a way that guarantees transactional consistency for all activities. There are multiple mutation arguments:

white check markCreate a new post and connect to an existing author via an email field.

white check markUpdate the title of any blog posts with the where action with a specific author ID.

white check markUpsert is similar to updating, but querying update and create at the same time.

white check markDelete the blog posts with the IDs you have defined.

white check markConnect (Scalar lists only) use the set action to connect a list of new values.

Create and Update Richly Defined List Content

Scalar lists, or unordered lists, allow for special mutations. This is a single blogPost on our company blog. By default we can give it tags for ordering and sorting. You can create integer, string, and boolean scalar lists.

Create
When creating new scalar content for blogPost values can be provided for each scalar list field using set.

  mutation {
    createBlogPost(data: {
      tags: {
        set: [
          "Serverless",
          "Backend Development"]
      }})
    id
  }

Update
When updating the existing content of a blogPost additional operations can be performed on the scalar list fields.

set
Override the existing list with an entirely new list.

push
Add one or more elements anywhere in the list. Coming Soon.

pop
Remove one or more elements from the beginning or the end of the list. Coming Soon.

remove
Remove all elements from the list that match a given filter. Coming Soon.

Batch Update and Delete Content

Batch mutations are useful to update or delete multiple content nodes at once. Updating takes a where parameter to specify which content to target and a data. parameter to specify what is updating. Here, we are deleting all unpublished Post nodes of a certain author.

  mutation {
    deleteManyBlogPosts(
      where: {
        status: DRAFT
        author: {
          name: "Jane Smith"
        }
      }
    ) {
      count
    }
  }

Interested in Learning More About Features of GraphCMS?

GraphCMS has all of the most important features of a robust content management system, while also pioneering proprietary features for the era of application content. Learn more in these landing pages all about GraphCMS' features.

The GraphCMS mutations API is a great example ouf our “least amount of opinion” mantra. We get out of your way and give you the control over your data.