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.
https://{your_salesforce_instance}.salesforce.com/services/data/{version}/ui-api

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.

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.

Sample apps and videos

We have two sample apps that shows how to use the UI API and various endpoints.

  1. Record Viewer is a Node.js app available at https://github.com/forcedotcom/RecordViewer.
  2. 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.

  1. User Interface webinar recording
  2. Dreamforce session recording

Documentation

You can find the UI API documentation here.

Conclusion

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.

Related Trailhead modules

  1. API basics
  2. Use REST API
  3. Apex Metadata API

Get the latest Salesforce Developer blog posts and podcast episodes via Slack or RSS.

Add to Slack Subscribe to RSS