Executing Queries and Mutations

Here are examples of the two supported operations in the GraphQL server: queries and mutations.

Queries permalink

Use the query operation to retrieve data (similar to a GET operation in REST).

Mutations permalink

Use the mutation operation to create, update or delete data (similar to a POST, PUT or DELETE operations in REST).

Handling Mutation Payloads 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 value SUCCESS or FAILURE
  • post and postID: the updated post object and its ID, if the update was successful
  • errors: a list of CustomPostUpdateMutationErrorPayloadUnion, 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 may 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
}
}
}