Mutations

Our GraphQL mutations in the external API let you create, update, and delete content entries. This is very useful in areas like form submissions and user inputs.

Security is crucial when changing data. You should never expose an API key with mutation access directly on the client-side. It's intended to be used in your API endpoint. You can put security measures like rate limits or captcha protection upfront. This helps ensure that only real users are submitting and changing the data, and no robots can breach your daily quota.

Usage example of Mutations

To enable mutations, you must first activate them within the blueprint. You can locate this setting in the blueprint overview, accessible via the dropdown menu associated with each individual blueprint.

In this instance, we'll use the BlogArticle blueprint from the blog starter template as an example. However, keep in mind that the process of enabling mutations applies uniformly across all blueprints, provided they are enabled.

To craft our first mutation, navigate to the 'Playground' found in the main menu. Start by writing a mutation query that will generate a new blog article with the slug "bar" and a teaser headline "Foo".

mutation ExampleMutation {
  createBlogArticle(input: {
    slug: "bar",
    teaserHeadline: "Foo"
  }) {
    id
    slug
    teaserHeadline
  }
}

Remember, executing this query will create a document, but it won't be published automatically. Thus, to retrieve the returned values — id, slug, and teaserHeadline — you need to include the preview header in the request.

{
  "x-caisy-preview": "true"
}

In our playground the headers can be set here:

By executing the above query with the preview header, you should receive a result similar to:

{
  "data": {
    "createBlogArticle": {
      "id": "77b22601-3506-4cd2-89aa-91d4ef23a5c5",
      "slug": "bar",
      "teaserHeadline": "Foo"
    }
  }
}

When working with mutations, it's considered best practice to make the input a variable. This allows you to pass a full JSON object as variables, as demonstrated below:

mutation createBlogArticle($input: BlogArticle_CreateInput!) {
  createBlogArticle(input: $input) {
    id
    slug
    teaserHeadline
  }
}

Your variables JSON object might look like the following:

json{
  "input": {
    "slug": "bar",
    "teaserHeadline": "Foo"
  }
}