Schema Conventions

Within the Salesforce GraphQL schema, there are several conventions that the types adopt to ensure that the schema performs as expected for your record data. Fundamentally, GraphQL API defines types that describe the set of data you can query from the UI API family. It also provides pagination, error querying, and versioning support.

Several operation types are available with GraphQL API.

  • Query- Provides an entry point for read operations.
  • Mutation- Provides an entry point for create, update, and delete operations. Mutation is available as a Beta Service in API v59.0–65.0 and is generally available in API v66.0 and later.

Each API family has a top-level field on the Query operation type, which serves as the entry point to that API family. The Query operation type has a uiapi field and rateLimit field. The rateLimit field is deprecated.

The Mutation operation type has a uiapi field with a UIAPIMutationsInput argument. The UIAPIMutationsInput has a boolean argument allOrNone that has a default value of true. When true, if one or more operations fails, all operations are rolled back and not executed.

User Interface API (UI API) is the only API family that participates in the schema. Access UI API via the uiapi field of type UIAPI.

UI API enables developers to build user interfaces so that users can work with records, list views, actions, favorites, and so on. It’s the API that powers Lightning Experience, Salesforce for Android, iOS, and mobile web. See the UI API Developer Guide.

The UIAPI type includes these fields.

Use the UIAPI type to:

The GraphQL server adopts the Relay Connection Specification for pagination. Pagination is a common way for a GraphQL server to structure types when dealing with a result set that requires iteration. See Paginate Results.

When reading data via the Query type, if an error occurs accessing a field, then the Errors list of the response includes the error. The error contains a path that associates the error with the originally requested field. See Status Codes and Errors Responses.

While most GraphQL servers don’t include a version in the URL to the GraphQL endpoint, the Salesforce GraphQL schema does. Various types of objects, such as sObjects, depend on the version for their construction. These objects require some version of the API to bind the request to. All new types and fields added to the Salesforce platform have an associated version. The API version dictates what capabilities the application server has when processing the request. For this reason, the GraphQL endpoint includes a version, which is the version of the API used during the request.