Schema Structure

Within the Salesforce GraphQL schema, there are a number of conventions that the types adopt for various cross-cutting concerns.

Each API family has a top-level field on the Query type, which serves as the entry point to that API family. User Interface API (UI API) is the sole 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 GraphQL Server adopts the Relay Connection Specification for pagination. This specification is a common way for a GraphQL server to structure types when dealing with a result set that must be iterated through. See the Pagination page on graphql.org for an introduction to pagination.

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.

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.