Handling mutation payloads
We can configure mutation fields to return either of these 2 different entities:
- A payload object type
- Directly the mutated entity
This guide explains how to handle the first option, the payload object type.
Handling the payload object type for mutations permalink
Mutations in the schema return some payload object, which provides any error(s) resulting from the mutation, or the modified object if successful (these 2 properties are most likely exclusive: either errors
or object
will have a value, and the other one will be null
).
Errors are provided via some "ErrorPayloadUnion" type, containing all possible errors for that mutation. Every possible error is some "ErrorPayload" type that implements the interface ErrorPayload
.
For instance, the operation updatePost
returns a PostUpdateMutationPayload
, which contains the following fields:
status
: whether the operation was successful or not, with either valueSUCCESS
orFAILURE
post
andpostID
: the updated post object and its ID, if the update was successfulerrors
: a list ofCustomPostUpdateMutationErrorPayloadUnion
, if the update failed.
The union type CustomPostUpdateMutationErrorPayloadUnion
contains the list of all possible errors that can happen when modifying a custom post:
CustomPostDoesNotExistErrorPayload
GenericErrorPayload
LoggedInUserHasNoEditingCustomPostCapabilityErrorPayload
LoggedInUserHasNoPermissionToEditCustomPostErrorPayload
LoggedInUserHasNoPublishingCustomPostCapabilityErrorPayload
UserIsNotLoggedInErrorPayload
Error type GenericErrorPayload
is contained by all "ErrorPayloadUnion" types. It is used whenever the specific reason for the error cannot be pointed out, such as when wp_update_post
simply produces WP_Error
. This type provides two additional fields: code
and data
.
Then, to execute the updatePost
mutation, we can execute:
mutation UpdatePost(
$postId: ID!
$title: String!
) {
updatePost(
input: {
id: $postId,
title: $title,
}
) {
status
errors {
__typename
...on ErrorPayload {
message
}
...on GenericErrorPayload {
code
}
}
post {
id
title
}
}
}
If the operation was successful, we will receive:
{
"data": {
"updatePost": {
"status": "SUCCESS",
"errors": null,
"post": {
"id": 1724,
"title": "This incredible title"
}
}
}
}
If the user is not logged in, we will receive:
{
"data": {
"updatePost": {
"status": "FAILURE",
"errors": [
{
"__typename": "UserIsNotLoggedInErrorPayload",
"message": "You must be logged in to create or update custom posts"
}
],
"post": null
}
}
}
If the user doesn't have the permission to edit posts, we will receive:
{
"data": {
"updatePost": {
"status": "FAILURE",
"errors": [
{
"__typename": "LoggedInUserHasNoEditingCustomPostCapabilityErrorPayload",
"message": "Your user doesn't have permission for editing custom posts."
}
],
"post": null
}
}
}