Overview
The Metadata API consists of two types of services: file-based and object-based. These service types are summarized next:
File-based services—The file-based services are deploy and retrieve. The deploy service takes a Base64-encoded zip file containing the components to deploy into the Force.com organization. The zip file must contain a manifest file named package.xml at its root to describe the contents of the zip. The retrieve service downloads metadata from Force.com and returns it as a zip file complete with package.xml as manifest. Its input is a RetrieveRequest object to specify the types of metadata to download. Both services can operate on up to 1,500 metadata objects per call.
Object-based services—The object-based services are create, update, and delete. To invoke create or delete, pass an array of Metadata objects. The Metadata object is the superclass of a wide array of objects that contain metadata for specific features of Force.com. For example, the CustomObject class represents a custom database object, and Layout represents a page layout. Unlike data records in which a unique identifier (Id) field is the key, metadata uniqueness comes from a combination of its type and fullName field. The update service takes an array of UpdateMetadata objects, which each contain a Metadata object and the current name of the object to replace.
Note
Force.com’s documentation uses the term declarative to describe its file-based services, and CRUD (for create, read, update, and delete) to describe its object-based services.
All Metadata API services are asynchronous, returning immediately with an AsyncResult object. This object contains a unique identifier for tracking the status of the asynchronous operation. For object-based services, the service to check status is called checkStatus. For the file-based service deploy, the status service is checkDeployStatus, and for retrieve, it’s checkRetrieveStatus.