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!
Create, Update, Upsert and Delete single nodes of your data types. Example: Create, update, or delete a blog post.
Update and Delete multiple nodes of your data in one go. Example: Change a batch of posts from Draft to Published.
Create, Update, Upsert and Delete single nodes of a certain object type. Example: Associate a batch of posts with a new Author.
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!
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.
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.
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.
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:
Create a new post and
connect to an existing author via an email field.
Update the title of any blog posts with the
where action with a specific author ID.
Upsert is similar to updating, but querying update and create at the same time.
Delete the blog posts with the IDs you have defined.
Connect (Scalar lists only) use the
set action to connect a list of new values.
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.
When creating new scalar content for
blogPost values can be provided for each scalar list field using
When updating the existing content of a
blogPost additional operations can be performed on the scalar list fields.
Override the existing list with an entirely new list.
Add one or more elements anywhere in the list. Coming Soon.
Remove one or more elements from the beginning or the end of the list. Coming Soon.
Remove all elements from the list that match a given filter. Coming Soon.
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.
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.