At Salesforce, we try to provide APIs for everything we build. Not only that, we want to make sure any APIs we do offer are purpose-built, versioned, and well-maintained. Virtually all our apps (Both web and mobile) are built on top of various distinct APIs. In this blog post, we go through details of the UI (User Interface) API and how you can use it to build custom apps with consistent user interfaces.
There are many use cases where customers build custom mobile or web apps that use Salesforce data and metadata—sometimes they want to just replicate all or partial Salesforce UI inside those apps. But Salesforce UIs are complex. The correct UI for any given user depends on various rules, permissions, and page layout configurations. All of these dependencies can be easily changed by an admin (or anyone with appropriate permissions) at any time to better fit business needs. It used to be very hard to build dynamic UIs and display them in custom apps that take care of all the rules and updates whenever changes are made.
That’s where the UI API comes in. Its main purpose is to make it simple to replicate all or part of a Salesforce UI according to rules and permissions inside a given custom app. Since UIs also allow the users to edit, update, or delete the data, the UI API further provides endpoints to even perform CRUD operations corresponding to each layout with ease.
UI API vs Metadata API
The Metadata API is intended for creating and editing metadata in an org during design. It is typically used to programmatically take backup of and clone Orgs. While it can be used to read layout and create a custom UI, user interfaces are not the main purpose and it doesn’t provide data or all the CRUD endpoints.
In contrast, the UI API’s main purpose is to provide endpoints to build efficient UI apps at runtime. Think of the Metadata API as mainly used by admins and developers to create/update and setup the Org or extract data from the Org itself. In contrast, the UI API is used by developers to build custom apps and is used every time an end user uses that custom app.
UI API vs “Describe” REST API
The “/describe/layout” endpoint of the REST API can be used for building Salesforce UIs on third-party apps. But it doesn’t go far enough. For example, it doesn’t deal with the associated data, doesn’t integrate CRUD operation endpoints, and other critical actions needed for building custom UI inside third-party apps. You can still use it but you’ll have to do a lot of additional work.
The UI API is specifically built to handle everything necessary to build custom UIs in third-party apps in just a single call or a few calls. The API’s response includes both the layout and the data itself. Furthermore the data is fully formatted and provides details like the state of each section, making it a much better API for building UIs. As we go further in the blog, you’ll see various benefits of using the new UI API.
UI API in Lightning Experience
One of the first clients built on top of the UI API is actually the Lightning Experience app itself. In fact, it’s used by the Lightning Data Service to display and update the UI anytime there is a change.
Before we go further, let’s discuss where you should use the new UI API.
When to use the UI API
The UI API comes in handy when you are building a custom web or desktop or a native mobile app outside of the Lightning Experience app. You may also use it to build a Lightning stand-alone app where you may want to display a small portion of the UI like a record page. You can simply call the UI API from your app and display Salesforce data exactly how it’s displayed in the Lightning Experience. You can also use the API for edit views and get all the benefits that are described in this blog.
When NOT to use the UI API
The UI API should not be used for things like data extraction or data uploads because UI APIs are very contextual. For example, if you want to extract data for some object, the UI API requires you to specify device form factor and may return fields that are available in that form factor.
If you are building a Lightning component inside Lightning Experience, your first choice should be to look at using Base components plus Lightning Data Service. Lightning Data Service provides additional features like cache management on top of UI APIs and is easier to use in most cases. But if it’s not sufficient, then think of using the UI API endpoint via Apex.
Benefits and features
1. Efficient response payload
The UI API provides both layout and data information in one place.
2. Provides formatted and localized value
For every field the UI API provides formatted values for all supported field types via “displayValue” attribute. This is extremely beneficial as you don’t have to format this for every field. Furthermore, the displayValue field provides localized values based on org/user locale settings.
3. Provides default or business field value
If the field has a no value set, the API automatically returns the default value or value generated from business rules or values for cloning Records.
4. Supports multiple form factors
The UI API supports three different device form factors for Desktop (“large”), Tablet (“medium”) and Mobile (“small”) devices and returns appropriate results for each one. For example, if you are viewing your app on a mobile device, you only get the data and layout appropriate for a mobile app.
5. Field-level security, sharing rules, and language support are built-in
FLS, sharing rules, language localization, and so on are already taken care of so you don’t have to deal with them in your app.
Three major endpoints
The main endpoint of the UI API is shown below, but the API is divided into three endpoints to deal with Records, Actions and Favorites.
1. RECORDS ENDPOINT
The Records endpoint “/ui-api/record-ui” allows you to essentially build any Record UI that can also do CRUD operation. The list below shows different things you can do with this endpoint.
- Get Record Data and Metadata
Get layout information, metadata, and data to build UI for a single record or for a collection of records.
- Get Record Layout Metadata
Get metadata about page layouts for the specified object type.
- Get Object Metadata
Get metadata about a specific object. The response includes metadata describing fields, child relationships, record type, and theme.
- Get Picklist Values
If a field’s dataType property is equal to Picklist, use this resource to get the picklist values.
- Get Child Records
Get child records for a specified record and child relationship name. Relationships are connections between records. On a record detail page, each record in a related list has a child relationship to the parent record.
- Get a Record
Get a record’s data.
- Get a Batch of Records
Get data for a batch of records.
- Create a Record
Create a record. First, make a request to the Clone Record Default or Create Record Default resources to get the default metadata and data for the record.
- Get Default Values to Clone a Record
Get the default layout information, object information, and data for cloning a record. After getting the default values, make a request to POST /ui-api/records to create the record.
- Get Default Values to Create a Record
Get the default values for fields for a new record of a specified object and optional record type. After getting the default values, make a request to POST /ui-api/records to create the record.
- Update a Record
Update a record’s data.
- Delete a Record
- Get Lookup Field Suggestions
When a user edits a lookup field, use this resource to search for and display suggestions. You can search for most recently used matches, matching names, or any match in a searchable field. You can also specify lookup filter bindings for dependent lookups.
- Get Lookup Field Suggestions for a Specified Object
When a user edits a lookup field, use this resource to search for and display suggestions for a specified object.
2. ACTIONS ENDPOINT
The actions endpoint “/ui-api/actions” returns metadata about all the actions such as standard actions and custom actions shown on a given page so you can build similar features in your custom app. The list below is from the docs for actions endpoint and shows various things you can do from this endpoint.
- Get Global Actions
Get the actions in the Global Actions menu.
- Get Record Detail Page Actions
Get the actions on record detail pages.
- Get Record Edit Page Actions
Get the actions on a record edit page.
- Get Related List Actions
Get the actions on related lists on a record detail page.
- Get Related List Record Actions
Get the actions on records in related lists.
- Get List View Header Actions
Get the header actions on list views.
- Get List View Record Actions
Get the record actions on list views.
- Get List View Chart Actions
Get the chart actions on list views.
- Get Lightning Page Actions
Get the actions on Lightning pages (FlexiPages).
- Get Lookup Field Actions
Get the actions on lookup fields.
- Get MRU List View Actions
Get the header actions on the most recently used (MRU) list view for objects.
- Get Photo Actions
Get the photo actions for pages. Currently, only group and user pages support photo actions.
3. FAVORITES ENDPOINT
The favorites endpoint “ui-api/favorites” provides access to view, create, and update favorite pages. The below list is from the docs for favorites endpoint and shows various things you can do from this endpoint.
- Create a Favorite
- Get a Favorite
- Get Favorites
Get all of a user’s favorites.
- Update a Favorite
- Update a Batch of Favorites
Update all favorites at once. The sort order is updated to the given relative ordering. Any favorites missing from the request body are deleted.
- Delete a Favorite
- Update Usage of a Favorite
Update the usage of an individual favorite, for example, the last time and number of times the favorite was clicked.
Sample apps and videos
We have two sample apps that shows how to use the UI API and various endpoints.
- Record Viewer is a Node.js app available at https://github.com/forcedotcom/RecordViewer.
- Record Viewer Native is a React Native app available at https://github.com/forcedotcom/RecordViewerNative
We also have a webinar and a Dreamforce session where we talk about the UI API in detail. We also did demos with the above two sample apps. If you have time, watch recordings to understand the UI API and the sample apps in deeper detail.
You can find the UI API documentation here.
If you are building a custom app and need to build a dynamic Salesforce UI inside it, the UI API should be your go-to place. Take it for a spin—we are sure you’ll really enjoy the power this API gives you.