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, the 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.

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

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 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.