Mutation

The mutation type defines how GraphQL operations change data. It is analogous to performing HTTP verbs such as POST, PATCH, and DELETE. The various mutation types supported in the GraphQL API are all sent using POST. The other HTTP verbs are not used.

All R-Service mutations accept a single input argument, an input type, which contains the values that are used by the mutation. Using a single input argument makes it easy to post whole JSON objects to the mutation using one GraphQL variable instead of making a separate variable for each argument. Using variables is recommended over including dynamic values directly in queries. Besides preventing security issues arising from including user supplied values in queries, using these variables also facilitates logging without including personal/sensitive data in log files.

A sample usage of a mutation to create a Request:

    mutation {
      requestCreate(input: { subject: "My request", category: "other" }) {
        errors {
          path
          message
        }
        request {
          id
          requestId
          subject
          category
        }
      }
    }

Note that for this example to work your OAuth token must have added a scope to allow action Request - Create.

Mutations

R-Service exposes the following mutations to allow data to be changed.

The query will be executed in the background. Typically the following fields should be queried:

  asyncQuery { resultUrl errorCount }
  configurationItems { id sourceID }

On initial submission the configurationItems field will be null. The resultUrl contains an expiring link to the location where the resulting JSON is available once the query has been executed. It is possible to poll the link every couple of seconds to check whether the query is completed. Initially the link will point to an empty JSON document ({}), once the query is completed it will contain the JSON result of this mutation. In the result both the asyncQuery and configurationItems fields as requested on submission are present. The errorCount can for example be used to see whether processing was successful (then it is 0).