GraphQL and the UI API
Module 4 of 7 in the chapter Salesforce as an API Provider, chapter 8 of the Integration Architect course. Each module stands on its own. Previous: Many in One Call · Next: Your Own Door: Custom Apex REST
The question this module answers: When should a client ask Salesforce for exactly the data it chooses, with GraphQL, or for a record the way the screen shows it, with the UI API?
Where this module sits on the map.
Module 2 gave the client two choices. Write a SOQL query and get the rows, or ask for one record by ID and get every field. Module 3 put many writes in one call. This module is about reading, and about a different idea: the client decides the shape of the answer.
GraphQL: The Client Decides
Section titled “GraphQL: The Client Decides”GraphQL isn’t a Salesforce invention. It’s an open industry standard, and Salesforce’s GraphQL API follows its specification. Three things make it different from the REST calls in module 2:
- One address. Every request goes to the same place, as a POST to
/services/data/v68.0/graphql. The question is in the body. - You get only what you ask for. The client lists the fields it wants, across several objects, and nothing extra comes back.
- It describes itself. You can ask the API what types and fields it has, so a client can discover the schema before it asks.
Salesforce puts it simply: “a single endpoint to call for all data needed in one request” (Get Started with GraphQL API (opens in a new tab), Salesforce Developers, checked 2026-10-31).
Take the crews’ mobile app at the start of a stop. It needs the Work Order’s status and address, and the items to deliver. With module 2, that’s a query for the Work Order and another for its line items, each returning whatever fields the query listed. With GraphQL, it’s one request that lists exactly those fields:
query NextStop { uiapi { query { WorkOrder(where: { Partner_Delivery_Key__c: { eq: "REDROCK-8472914-1" } }) { edges { node { Status { value } Street { value } WorkOrderLineItems { edges { node { Description { value } } } } } } } } }}The server tailors the answer to the client. I think of it as a composite for queries, except you get to pick and choose and mix and match. On a phone, on a slow connection, that matters: fewer round trips, and a smaller answer.
It goes further than records. In my GraphQL videos, I put three kinds of question into one request: records from two unrelated objects with a filter, the schema of those objects (their fields and which ones can be created), and aggregates, the average, total and largest opportunity amount. The answer came back in under a second. And because the API describes itself, Postman read the schema and finished my field names as I typed, the same introspection a developer’s tools use.
And since API 66.0 (Spring ‘26), GraphQL can write as well as read. Mutations, which create, update and delete records, went from beta to generally available (Mutations (opens in a new tab), checked 2026-10-31). One limit to know: a mutation can’t yet create a record together with its children. For a manifest with its deliveries, module 3’s composite graph is still the tool.
What GraphQL Doesn’t Change
Section titled “What GraphQL Doesn’t Change”One request isn’t one API call. This is where GraphQL and composite differ. Salesforce’s limits are specific (GraphQL API Query Limitations (opens in a new tab), checked 2026-10-31):
- up to 10 subqueries in one GraphQL query, and each subquery counts as one request for rate limiting;
- up to 2,000 records per subquery;
- 10 records by default, unless you ask for more and page through the rest.
That last one catches people. A query that returns 10 deliveries in testing hasn’t returned all of them; it’s returned the default page. The client asks for more and follows the page cursor, the same lesson as nextRecordsUrl in module 2. And GraphQL uses the Connect API’s rate limits; go over them and the answer is 503 Service Unavailable (API Request Limits (opens in a new tab), checked 2026-10-31).
Security doesn’t change either. GraphQL honors “the object-level security and field-Level security of the context user”, so “two different users can have two different views of the GraphQL schema” (What is GraphQL API? (opens in a new tab), checked 2026-10-31). The integration user still decides what the client can see. From API 68.0, an admin also decides in Setup, under API Access Controls, whether a site’s guest user can reach GraphQL at all. Chapter 13 is about guest users and why that setting matters.
The UI API: Give Me the Screen
Section titled “The UI API: Give Me the Screen”Now the opposite idea. Look at a Work Order in Salesforce. There’s a lot on the screen: the fields, in sections, in the layout the admin built; the picklist values; the related lists; the buttons. Getting all of that through module 2’s calls could take a dozen requests, and then the client still has to work out the layout and which fields this user may see.
The User Interface API does that work for you. It’s “the same API that Salesforce uses to build Lightning Experience and Salesforce for Android, iOS, and mobile web”, and it returns “data and metadata in a single response”. In Salesforce’s words: “You don’t have to worry about layouts, picklists, field-level security, or sharing” (Get Started with User Interface API (opens in a new tab), checked 2026-10-31). One call shows it:
GET /services/data/v68.0/ui-api/record-ui/0WOxx0000004C92GAEBehind that call, Salesforce checks the user’s access, queries the record, and gets the layout and the object’s metadata. What comes back is everything the screen would show, for this user. You can see the actions too: ask for a record’s actions and you get the buttons this user could press. It’s almost like driving Salesforce’s screens through the API. And it writes as well as reads. POST /ui-api/records creates a record (Create or Clone a Record (opens in a new tab), checked 2026-10-31), with the same rules a user would meet on the screen. Ask for the layout of an object, or its full object metadata, and you get those too, each in one call.
So if a Retail Partner builds its own app to show a delivery the way Steve Trucking’s screen shows it, the UI API is the door. When Steve Trucking’s admin adds a field to the layout, the partner’s app shows it, with no change on the partner’s side. The answer follows the org.
The price is size. The UI API answer is big, because it’s everything. In my video on it, the answer for one account came back in a quarter of a second, so it isn’t slow. It’s heavy. I wouldn’t use it where every byte counts, or where the client only needs two fields. That’s GraphQL’s job.
Two ways to read. The client chooses the fields, or the org chooses the screen.
Which One?
Section titled “Which One?”| The client needs | Use |
|---|---|
| A few fields from several objects, on a phone or a slow connection | GraphQL |
| A record exactly as Salesforce’s screen shows it, layout and all | UI API |
| Rows for a report or a sync, in a fixed shape | REST query (module 2) |
| Records that belong together, written whole | Composite graph (module 3) |
GraphQL and the UI API are mostly for building user interfaces outside Salesforce: mobile apps, portals, a partner’s own screens. Your Lightning web components use them too, through the GraphQL wire adapter and the UI API’s adapters. Server-to-server integrations, like Redrock’s nightly manifest, usually stay with REST and composite.
Watch it on video
Section titled “Watch it on video”In early 2024 I made three videos on these: an introduction to GraphQL, a combined GraphQL request, and the UI API. The notes under the videos say what’s still right and what’s changed since.
What an Architect Decides Here
Section titled “What an Architect Decides Here”- Who decides the shape of the answer. The client (GraphQL), the org’s layout (UI API), or a fixed query (REST).
- How the caller pages. GraphQL returns 10 records unless asked for more; the client follows the cursor to the end.
- What it costs against the limits. Each GraphQL subquery counts as a request; composite counts as one call. Pick by the shape of the work, then check the count.
- Who can reach it without signing in. From API 68.0, guest access to GraphQL is a setting. Decide it on purpose.
Explore
Section titled “Explore”- Get Started with GraphQL API (opens in a new tab): Salesforce Developers, with Query Limitations (opens in a new tab) and Mutations (opens in a new tab) (checked 2026-10-31)
- GraphQL (opens in a new tab): the open standard and its specification
- Get Started with User Interface API (opens in a new tab): User Interface API Developer Guide (checked 2026-10-31)
- The API Guide: GraphQL and the UI API with the rest of the doors
- Salesforce Developers, GraphQL API, API Request Limits (opens in a new tab), checked 2026-11-07.
- Salesforce Developers, GraphQL API, What is GraphQL API? (opens in a new tab), checked 2026-11-07.
- Salesforce Developers, User Interface API Developer Guide, Create or Clone a Record (opens in a new tab), checked 2026-11-07.