Start tracking your progress
Trailhead Home
Trailhead Home

Get Started With User Interface API

Learning Objectives

After completing this unit, you’ll be able to:
  • Explain where User Interface API fits into the Salesforce Platform.
  • Describe when to use User Interface API.
  • Describe when not to use User Interface API.

Access the Salesforce Platform at Your Level

The power of Salesforce is that you can customize it to work for you and your customers. When we decided to rebuild our UI, we didn’t reskin it, we built a powerful platform that gives you even more access to customize Salesforce. That’s Lightning.

Lightning is the Salesforce user experience (Lightning Experience), platform, and UI framework (Lightning Component framework). Lightning lets you customize Salesforce at the level that works for your skills and your requirements by giving you access to different layers of the Salesforce Platform. In this module, you’ll learn to access the platform using User Interface API, which Lightning Experience uses to get data and metadata from Salesforce.

A little background. To build Lightning Experience, we needed a new API. Our existing API didn’t provide access to everything we needed, and it was designed for data integration, not for building user interfaces. And so, on a warm, cloudless day, User Interface API was born.

We worked closely with our internal Salesforce developers to find out which jobs were difficult and time-consuming, and we solved those problems. We made this new REST API public, which means that you can build web apps and mobile apps using the same API that Salesforce uses to build Lightning Experience and the Salesforce apps for Android and iOS.

Cruising the Lightning Technology Stack

You’ve got lots of ways to access Lightning to build Salesforce apps that make life easier for you and your customers. Let’s look at the layers of the Lightning technology stack to understand where User Interface API sits and when to use it.Layers of the Salesforce Platform. UI API is under Lightning Data Service, which is under Lightning Components.

As you go up the stack, Lightning Platform does more for you, and development gets easier. At the top of the stack, you don’t write code, you point and click. At the bottom of the stack, you write lots of code.

  • Drag pre-built Lightning components in Lightning App Builder.
  • Develop custom Lightning components.
  • Use Lightning Data Service to access Salesforce data in Lightning components.
  • Use User Interface API to build custom web and mobile apps that connect to Salesforce from off the Salesforce platform.

Let’s look at the top of the stack, at the “no code” solution. Lightning base components, like button and input and icon, are the UI building blocks. In Lightning App Builder, without using any code, you can combine components to create apps that live in Salesforce. You can also build stand-alone apps that are hosted on the Salesforce platform.

Moving down the stack, you can build your own Lightning components. Without much code, you can use Lightning Data Service to create, read, update, and delete records. Lightning Data Service uses User Interface API (which sits right below it in the stack) to get data from Salesforce. LDS adds caching magic, which minimizes trips to the server and updates all records that use the same data.

The foundation of the Lightning stack is User Interface API, which gives you payloads of Salesforce data and metadata that are structured for building UI. Use your favorite web framework or language to build any custom web or native mobile app that you can imagine. React, Vue, Angular, iOS, Android...if you can make an HTTP request, you can use User Interface API.

User Interface API Makes It Easy to Develop UI

Salesforce has many APIs and it can be difficult to know which is the best tool for the job. If you’re building a custom web or mobile app and need a user interface that lets users view, create, edit, and delete Salesforce records—a user interface that looks and behaves like Salesforce—UI API is the way to go.

If you’re building a user interface to let users edit dependent picklists and lookups, User Interface API is definitely the way to go. User Interface API has a resource that makes it a whole lot easier.Dependent picklist editor shows you menus for Country, Language, State, and City.

As we’ve mentioned, Salesforce uses User Interface API to build Lightning Experience. UI API is developed by one set of internal Salesforce engineers to make life easier for another set of internal Salesforce engineers who develop Lightning Experience. And we’re super excited to see what you build with it, too!

Let’s face it, the Salesforce user interface is complex. The correct UI for any particular user depends on various rules, permissions, and page layout configurations. An admin can change any of these dependencies to better fit business needs. For example, an admin can add or remove fields from page layouts, mark fields as required, and assign page layouts to profiles.

It used to be hard to build dynamic UI to work with records in custom apps because you’d have to write code to update the UI whenever an admin made metadata changes to the org.

That’s one of the reasons we built UI API, and why we’re adding new features every release. UI API makes it simple to build a custom user interface according to the rules and permissions inside a Salesforce org because the UI responds to metadata changes at runtime. Let’s say it again for good measure—you don’t need to modify your app when an admin changes permissions, layouts, field-level security, or sharing rules. In fact, you don’t have to write code that checks for any of those things, UI API does it for you.

Before UI API, you’d have to make lots of calls to get the information you need for layout (where do the fields live on the page), metadata (which fields does an object have, and are they required), and record data (what are the field values). UI API makes those calls for you and gives you an easy to parse response—it does the work of a layout rendering engine, so you don’t have to build one yourself. Your recliner (or snowboard, or garden) awaits.

Oh, and UI API has the same API limits as Enterprise API, so don’t worry about learning a new way to track API limits.

Efficient Payloads
You need a lot of information to build forms that let users work with records. Which fields does the object have? Are they required? Where should they be positioned in the layout? What are the values of all the fields? UI API payloads aggregate the data and metadata so you don’t have to make lots of API requests.
Formatted and Localized Display Values
Speaking of field values, UI API gives you values that are ready to display in the user’s language of choice. If it’s a date or a currency, it’s formatted nicely. No matter what data type the field has, your code just uses the displayValue property.
Field-level Security and Sharing Rules
UI API respects them. If a user doesn’t have access to a field, the field isn’t included in the response. Boom. Enjoy your free time.
Business Logic
Every developer faces the same problems. For example, to develop a user interface that lets users clone a record, you need different information than you need when you develop a user interface that lets users create a record. A clone form includes data values from the cloned record, whereas most of the data values in a create form are null (Owner and OwnerId are non-null). UI API has resources that return the necessary information to develop user interfaces for these use cases, and they’re the same resources we use to build Lightning Experience and Salesforce for Android, iOS, and mobile web. You get the same default values that you’d see in Salesforce—pretty cool.
Layout Types and Form Factors
Do you want your app to work on any device, tablet, or desktop? Of course you do. UI API responses can provide full and compact layout types, and small, medium, and large form factors.
Access Modes
To build an app that lets users work with Salesforce records, you have to build different user interfaces for the different types of work. Is the user viewing, creating, cloning, or editing a record? You can request a payload for each of these access modes. (Although cloning uses edit mode, so there are only three modes: create, edit, and view.)

When Shouldn’t I Use User Interface API?

Don’t use User Interface API for system integration. Or to create an automated integration for uploading or extracting data. Or to upload or extract data in bulk. Use the Enterprise API or the Bulk API for those tasks.

If you’re building Lightning components, don’t use UI API directly, use Lightning Data Service (LDS).

LDS is built on User Interface API, but it also caches responses and updates all records that are affected by the data changes. When you’re working with LDS, you don’t have to worry about making REST calls and caching results, because LDS does it for you. And when data changes, LDS updates all the relevant components. Not only does LDS eliminate inconsistent data between components, it also lets users work offline and syncs the data when they go back online. LDS is cool.

And finally, don’t use User Interface API to rebuild the entire Salesforce UI. Why would you want to do that?

Get to Know the User Interface API Resources

The UI API resources fall into a few categories. This Trailhead module looks in-depth at records and layouts resources, but let’s quickly go over some of the other categories so you know what’s possible. To see the complete list of resources, check out the User Interface Developer Guide.

Tip

Tip

In this module, resource and endpoint are used interchangeably.

Records and Layouts

Use these resources to create, read, update, and delete Salesforce records.

The quintessential UI API resource takes one or more record IDs and returns data, metadata, and layout information. That’s right, your app makes one HTTP request and gets everything you need to display a record. We’ll talk more about this resource in the next unit.

/ui-api/record-ui/{recordIds}
UI API also has resources to get these same layout, object metadata, and data responses individually.
/ui-api/layout/{objectApiName}
/ui-api/object-info/{objectApiName}
/ui-api/records/{recordId}
In a later unit, we look at resources that get the default field values that you need to build UI for cloning or creating a record.
/ui-api/record-defaults/create/{objectApiName}
/ui-api/record-defaults/clone/{recordId}
We’ll also learn how to use this resource to get the values for all the picklist fields of a specific record type.
/ui-api/object-info/{objectApiName}/picklist-values/{recordTypeId}

List Views

Salesforce users spend a lot of time customizing their list views so they can view and analyze records. Use UI API to get a list of records and list view metadata. Like the /ui-api/record-ui/{recordId} resource, these resources return data and metadata in one response.
/ui-api/list-ui/${listViewId}
/ui-api/list-ui/${objectApiName}/${listViewApiName}
You can also get the data and metadata in their own resources.
/ui-api/list-info/${listViewId}
/ui-api/list-info/${objectApiName}/${listViewApiName}
/ui-api/list-records/${listViewId}
/ui-api/list-records/${objectApiName}/${listViewApiName}

Actions

Actions give users a quick and easy way to complete tasks in Salesforce. Use actions to create an object, send an email, or log a call, and so on. Actions show up in the action bar in the mobile app and in the actions ribbon in Lightning Experience. Before UI API, apps had to use SOQL to find out which actions were available. Now, you can fetch lists of actions that are available to the user in the Salesforce app, in the Global Actions header, on the record detail and edit pages, on related lists, and more.
/ui-api/actions/global
/ui-api/actions/record/${recordIds}
/ui-api/actions/record/${recordId}/record-edit
/ui-api/actions/record/${recordId}/related-list/${relatedListIds}
// There are more actions resources! Check the User Interface API Developer Guide! 

Currently, you can use the actions endpoints to fetch lists of actions, but you can’t execute actions. It’s handy to get a list of actions if you want to use quick actions, if you have Visualforce overrides, or if you want to determine CRUD based on visible actions. For example, if a New action exists, then a user can create a record, and the same is true with Edit and Delete.

Favorites

Lightning Experience has a star in the header that holds your favorite records and list views. Users can add favorites so they can navigate quickly in Salesforce. UI API has resources to create, view, update, and delete favorites so you can build this same favorites navigation in your custom apps.
/ui-api/favorites
/ui-api/favorites/${favoriteId}
/ui-api/favorites/batch
/ui-api/favorites/${favoriteId}/usage

Lookups

Salesforce objects often include lookup fields that allow you to associate two records together in a relationship. For example, a contact record includes an Account lookup field that associates the contact with its account. On record edit pages, lookup fields let you search for the record that you want to associate with the record you’re editing. Lookup UI for an Account name. The dropdown contains suggestions.

Building the user interface for lookups and dependent lookups is a tough challenge that User Interface API makes much easier. Use these resources to create a user interface that lets users do a full type-ahead search that matches what you see in Lightning Experience.
/ui-api/lookups/{objectApiName}/{fieldApiName}
/ui-api/lookups/{objectApiName}/{fieldApiName}/{targetApiName}
retargeting