Explore Salesforce APIs
Learning Objectives
After completing this unit, you’ll be able to:
- Describe the two main parts of an XML document.
- Identify the API to use when writing a package.xml manifest.
XML Structure
XML files have a structure and set of rules to operate by. An XML document has two primary sections, the declaration and the elements (or element trees). The structure of the element trees is important, but before we dive into how you set up your XML elements, let’s take a look at some rules of XML.
- Start tags (like
<types>) must have corresponding close (</types>) tags.
- Element names are case sensitive and should always be lowercase. For example:
<members>and<types>should be written lowercase.
- When you’re working with Salesforce metadata, be sure to declare a version for all of the metadata components to conform to the latest version:
<version>58.0</version>
This table describes the structure and uses of tags for Salesforce.
Name |
Description |
|---|---|
<types> |
This element contains one or more <members> tags and one <name> tag, and is used to list the metadata components of a certain type to retrieve or deploy. |
<members> |
The full name of a component. There is one <members> element defined for each component in the directory. This is a child element of <types>. |
<name> |
Contains the type of the component, for example CustomObject or Profile. There is one name defined for each component type in the directory. This is a child element of <types>. |
<version> |
The Metadata API version number of the files being retrieved or deployed. When deploying, all the files must conform to the same version of the Metadata API. |
XML Declaration
The first line of the document is the XML declaration. The XML declaration is a processing instruction that simply says the document is XML and tells the system how to process the file.
Example:
<?xml version="1.0" encoding="UTF-8"?> <Package xmlns="http://soap.sforce.com/2006/04/metadata">
XML Element Trees
XML element trees identify the metadata component directly and have a hierarchical structure.
- The tags start at the root (
<types>).
- Next are the parent tags identifying a component group (
<name>). This tells the system what type of component to look for, such as a CustomObject or a FlexiPage (Lightning page).
- The next tag identifies the specific component you wish to include in the XML file (
<members>).
Here is an example of the name and member tag structure in action.
When you create XML manifest files, you declare specific metadata types in between the <name> tags (1), and the name of the component you wish to reference in between the <members> tags (2).
In the example above, we’re calling on two objects in one metadata type. A custom object named Sticker__c and the sObject named Contact are both identified under the CustomObject metadata type. We’re also calling to a Lightning Record page named Sticker_Record.
Next, let’s take a look at how you decide which API to use in the package.xml file.
APIs Everywhere!
Salesforce provides many different APIs that give you programmatic access to your org. As you begin exploring protocols and learn more detail about how each API works, check out this table of all the APIs Salesforce has made available for you to use.
API NAME |
PROTOCOL |
DATA FORMAT |
COMMUNICATION |
|---|---|---|---|
REST API |
REST |
JSON, XML |
Synchronous |
SOAP API |
SOAP (WSDL) |
XML |
Synchronous |
Chatter REST API |
REST |
JSON, XML |
Synchronous (photos are processed asynchronously) |
User Interface API |
REST |
JSON |
Synchronous |
Analytics REST API |
REST |
JSON, XML |
Synchronous |
Bulk API |
REST |
CSV, JSON, XML |
Asynchronous |
Metadata API |
SOAP (WSDL) |
XML |
Asynchronous |
Streaming API |
Bayeux |
JSON |
Asynchronous (stream of data) |
Apex REST API |
REST |
JSON, XML, Custom |
Synchronous |
Apex SOAP API |
SOAP (WSDL) |
XML |
Synchronous |
Tooling API |
REST or SOAP (WSDL) |
JSON, XML, Custom |
Synchronous |
API for Package.xml
We’ve learned now that metadata are the components in the org and there are xml files associated with those components. It’s the coded file that defines the specific attributes of a component. You might be wondering, how do you interact with this file? Well that’s the power of Metadata API and SOAP API.
Not every piece of metadata is available declaratively through the user interface (UI). Metadata types such as Profiles are not available declaratively in Package Manager. You can use the Salesforce SOAP API to discover and find metadata that can be retrieved with package.xml.
-
SOAP API = The SOAP API Developer Guide provides a great overview of objects, their purpose, and useful entity relationship diagrams (ERD) that illustrate important relationships between objects.
-
METADATA API = Use Metadata API to call on specific metadata types in package.xml. Sometimes, certain metadata types aren’t accessible, or aren’t exposed in the way you’d expect (such as some permissions in profiles). It’s a good idea to reference the Metadata API Developer Guide to know what metadata type to declare in between the
<name>tags in package.xml.
Finding the Right Metadata Component Name
When working with Salesforce Metadata API and package.xml, knowing what metadata type to use for each of your components can be challenging.
For example, if you’re calling on an object, whether it’s custom or standard, you’d use the <CustomObject> metadata type. If you’re retrieving a Lightning Record page, the metadata type is <FlexiPage>. Most metadata types are straightforward, but some aren’t obvious, and may take a bit of digging. If you ever feel lost, don’t forget that SOAP API and ERD illustrations can almost always point you in the right direction.
Now that you know how XML is structured and which API to use, let’s write our first XML file!
Resources
- Salesforce Help: Which API Do I Use
- Salesforce Metadata API Developer Guide: Understanding Metadata API
- Salesforce Metadata API Developer Guide: Metadata Types
- Salesforce SOAP API Developer Guide: Data Model
- Salesforce CLI Command Reference: force:source CLI commands