Schema Conventions

Within the Salesforce GraphQL schema, there are a number of conventions that the types adopt to ensure 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 in API v59.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 a rateLimit field.

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

User Interface API (UI API) is currently the only API family that participates in the schema, and can be accessed via the uiapi field of type UIAPI.

UI API enables developers to build user interfaces that let users work with records, list views, actions, favorites, and more. 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.

Using the UIAPI type, you can:

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 must be iterated through. See Paginate Results.

When reading data via the Query type, if an error occurs accessing a field, then an error is added within the Errors list of the response. The error contains a path that can be used to associate 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 depend on the version for their construction, such as sObjects, which necessitates some version of the API to bind the request to. All new types and fields added to the Salesforce platform have an associated version, and the API version dictates what capabilities the application server has when processing the request. For this reason, the GraphQL endpoint embeds a version in the url, which is the version of the API used for the duration of the request.