GETTING STARTED
CHAPTER 1
Understanding Metadata API
Use Metadata API to retrieve, deploy, create, update or delete customization information, such as custom object definitions and page layouts, for your organization. This API is intended for managing customizations and for building tools that can manage the metadata model, not the data itself. To create, retrieve, update or delete records, such as accounts or leads, use data SOAP API or REST API .
The easiest way to access the functionality in Metadata API is to use the Force.com IDE or Force.com Migration Tool. Both tools are built on top of Metadata API and use the standard Eclipse and Ant tools, respectively, to simplify working with Metadata API.
•
Force.com IDE is built on the Eclipse platform, for programmers familiar with integrated development environments. Code, compile, test, and deploy from within the IDE.
•
The Force.com Migration Tool is ideal if you use a script or the command line for moving metadata between a local directory and a
Salesforce org.
For more information about the Force.com IDE or Force.com Migration Tool, see developer.salesforce.com
.
The underlying calls of Metadata API have been exposed for you to use directly, if you prefer to build your own client applications. This guide gives you more information about working directly with Metadata API.
You can use the Metadata API to manage setup and customization information (metadata) for your organizations. For example:
•
Export the customizations in your organization as XML metadata files. See Working with the Zip File
and retrieve()
.
•
Migrate configuration changes between organizations. See deploy()
and
retrieve()
.
•
Modify existing customizations in your organization using XML metadata files. See
deploy()
and retrieve()
.
•
Manage customizations in your organization programmatically. See
CRUD-Based Metadata Development
.
You can modify metadata in test organizations on Developer Edition or sandbox, and then deploy tested changes to production organizations on Enterprise, Unlimited, or Performance Editions. You can also create scripts to populate a new organization with your custom objects, custom fields, and other components.
SEE ALSO:
Deploying and Retrieving Metadata
CRUD-Based Metadata Development
Metadata Components and Types
Supported Salesforce Editions
To use Metadata API, your organization must use Enterprise Edition, Unlimited Edition, Performance Edition, or Developer Edition.
If you are an existing Salesforce customer and want to upgrade to Enterprise, Unlimited, or Performance Edition, contact your account representative.
It is strongly recommended that you use a sandbox, which is an exact replica of your production organization. Enterprise, Unlimited, and Performance Editions come with free developer sandboxes. For more information, see http://www.salesforce.com/platform/cloud-infrastructure/sandbox.jsp
.
1
Understanding Metadata API Development Platforms
Alternatively, you can use a Developer Edition org, which provides access to all of the features available with Enterprise Edition, but is limited by the number of users and the amount of storage space. A Developer Edition org isn’t a copy of your production org, but it provides an environment where you can build and test your solutions without affecting your organization’s data. Developer Edition accounts are available for free at http://developer.salesforce.com/signup
.
Note: A metadata component must be visible in the org for Metadata API to act on it. Also, a user must have the “API Enabled” permission to have access to metadata components.
Metadata API Access for Professional Edition
ISV partners can request Metadata API access to Professional Edition orgs for apps that have passed the AppExchange Security Review.
Access is granted through an API token (client ID). This special key enables the app to make Metadata API calls to customers’ Professional
Edition orgs.
As an ISV partner, you can request Metadata API access by following these steps.
1. Submit your app for security review. See Steps in the Security Review in the
ISVForce Guide
.
2. After your app is approved, log a case in the Partner Community in AppExchange and Feature Requests > API Token Request, and specify SOAP for the type of token.
To make calls to the Metadata API, append the API token to the CallOptions
SOAP header in your calls.
Development Platforms
Metadata API supports both file-based and CRUD-based development.
File-Based Development
The declarative or file-based asynchronous Metadata API
deploy()
and
retrieve()
operations deploy or retrieve a
.zip
file that holds components in a set of folders, and a manifest file named package.xml
. For more information, see
Deploying and Retrieving
Metadata
on page 15. The easiest way to access the file-based functionality is to use the Force.com IDE or Force.com Migration Tool.
CRUD-Based Development
The
CRUD Metadata API calls act upon the metadata components in a manner similar to the way synchronous API calls in the enterprise
WSDL act upon objects. For more information about the enterprise WSDL, see the
SOAP API Developer's Guide
.
Standards Compliance
Metadata API is implemented to comply with the following specifications:
Standard Name
Simple Object Access Protocol (SOAP) 1.1
Website
http://www.w3.org/TR/2000/NOTE-SOAP-20000508/
Web Service Description Language (WSDL)
1.1
http://www.w3.org/TR/2001/NOTE-wsdl-20010315
WS-I Basic Profile 1.1
http://www.ws-i.org/Profiles/BasicProfile-1.1-2004-08-24.html
2
Understanding Metadata API Metadata API Support Policy
Metadata API Support Policy
Salesforce supports previous versions of Metadata API. However, your new client applications should use the most recent version of the
Force.com Metadata API WSDL file to fully exploit the benefits of richer features and greater efficiency.
Backward Compatibility
Salesforce strives to make backward compatibility easy when using the Force.com platform.
Each new Salesforce release consists of two components:
•
A new release of platform software that resides on Salesforce systems
•
A new version of the API
For example, the Spring '07 release included API version 9.0 and the Summer '07 release included API version 10.0.
We maintain support for each API version across releases of the platform software. The API is backward compatible in that an application created to work with a given API version will continue to work with that same API version in future platform software releases.
Salesforce does not guarantee that an application written against one API version will work with future API versions: Changes in method signatures and data representations are often required as we continue to enhance the API. However, we strive to keep the API consistent from version to version with minimal, if any, changes required to port applications to newer API versions.
For example, an application written using API version 9.0, which shipped with the Spring ’07 release, will continue to work with API version 9.0 on the Summer ’07 release, and on future releases beyond that. However, that same application might not work with API version 10.0 without modifications to the application.
API End-of-Life
Salesforce is committed to supporting each API version for a minimum of three years from the date of first release. In order to mature and improve the quality and performance of the API, versions that are more than three years old might cease to be supported.
When an API version is to be deprecated, advance notice is given at least one year before support ends. Salesforce will directly notify customers using API versions planned for deprecation.
Related Resources
The Salesforce developer website provides a full suite of developer toolkits, sample code, sample SOAP messages, community-based support, and other resources to help you with your development projects. Be sure to visit https://developer.salesforce.com/page/Getting_Started
for more information, or visit http://developer.salesforce.com/signup
to sign up for a free Developer Edition account.
You can visit these websites to find out more about Salesforce applications:
•
Salesforce Developers provides a wealth of information for developers.
•
Salesforce for information about the Salesforce application.
•
Force.com AppExchange for access to apps created for Salesforce.
•
Salesforce.com Community for services to ensure Salesforce customer success.
3
