Various flavors of APIs are the powerhouses of the Salesforce Platform, providing for all your data and metadata needs. From REST to SOAP, and from Enterprise to Metadata, Salesforce APIs support a wide range of solutions. In order to wire up your application to Salesforce in the right way, you’ll need to understand these APIs and determine which ones can help you solve your needs. In this blog post, we’ll introduce you to the Salesforce Metadata API and delve into its importance and use cases.

Most of us are aware of the standard definition of metadata: data about data. But what does this mean in a Salesforce context? Salesforce metadata describes the schema, processes, presentation, authorization, and general configuration of your Salesforce org. It describes the properties of business data, which in turn determines how data records for your business are stored. Metadata even describes your code artifacts and how they’re meant to be used and behave in the Salesforce runtime.

The Salesforce Metadata API helps you to move this metadata between orgs during the development process. It doesn’t work with the business data itself. It lets you deploy, retrieve, create, update, or delete your org’s configuration information in two ways:

• Using deploy and retrieve calls — These calls are directly implemented in the API and are designed to overwrite the metadata in their destination. They move metadata to or from your org according to a manifest file that lists which metadata is to be acted upon. Often, these are used to move the entire set of metadata into or out of an org such as moving a set of changes to your production environment.
• Using push and pull commands — These commands are abstractions built on deploy and retrieve that use a secondary change tracking feature (or source tracking). They deal strictly with changed metadata and will report conflicts instead of overwriting. These are helpful to developers as they build new features.

NOTE: The metadata that describes an org is in constant change as new features are added. Not every feature is available in every version of the API. You can track which features are supported by each version of the Metadata API in the metadata coverage report.

Say you are a developer at Zephyrus, a talent-mobility firm that specializing in domestic and international employee relocation services. Zephyrus is expanding into Asia and South America. You’ve been asked to add new features that support regulatory differences for the new regions.

Let’s see how the Metadata API supports the development and release processes. We’ll use this example flow from the Salesforce architecture release management templates. Zephyrus has not yet adopted a full CI/CD workflow, so they use the org-based development model without source control.

• The start of the development process would begin with creating the necessary sandboxes to do the work that you need to do. Sandboxes are clones of your production org and don’t require the Metadata API to be generated.
• You decide to bring down all of the changes and configurations into your local project. You will make use of retrieve for this purpose as surfaced through the Salesforce CLI force:source:retrieve command.

• The new feature is going to require some new fields on existing objects. After making those changes in the org, you use pull to retrieve only the changes you made locally to your project via the force:source:pull command.

• Your work also entails changes to some existing Lightning Web Components and Apex classes. You make those changes locally and want to see them work in your org. You can use the push command through force:source:push. Just like with pull, only the changes that you made are moved to your sandbox.

• After your isolated testing is satisfactory, you definitely want to test the feature in various integration environments, such as developer, developer pro, partial sandboxes, or full sandboxes. You can use deploy through the force:source:deploy command to move the metadata to these upstream sandboxes for integration, UAT, and end-user training.

• After completion, you are ready to use the Metadata API to move your changes to production.

These are just the simplest of operations to demonstrate how developers use the Metadata API in their ALM processes. But for a deeper dive into these use cases and others, see Use Cases for Metadata API.

In addition, processes that you regularly use for code promotion or admin work use the Metadata API under the hood. Both change sets and the newly piloted DevOps Center rely on this API to move the changed metadata or source code between your Salesforce orgs, where you work with it (your local file system/version control).

The Metadata API is one of the core Salesforce APIs, allowing you to seamlessly move your metadata around to easily suit your changing configuration needs. Use this quickstart guide to learn more about the API, to start using it for your setup purposes, or to gain a better understanding of how you might already be taking advantage of the Metadata API!

About the authors

Neha Ahlawat is a Senior Product Manager at Salesforce focused on Metadata and Tooling APIs, source tracking, and metadata coverage. You can follow her on Twitter @ahlawat_neha.

Laurie Lee was a Summer 2021 Futureforce Intern at Salesforce focused on documenting Metadata and Tooling APIs. She’s currently a senior at Washington and Lee University, majoring in Computer Science.

Further reading and helpful links

Which Salesforce API should I use?
Understanding the Metadata API
Quick Start guide: Metadata API