The Metadata and Tooling API’s for me come under a similar category of API’s in that they are to do with the definition of data rather than data. These notes were compliled while studying for my Integration Architect certification in Autumn/Winter 2021/2022.
Metadata is data that describes other data. So rather than the content of a field, it describes the field type and its definition. It is as granular as that and as vast as the specific information and definition of how each Salesforce Org functions. It defines the schema, processes, the presentation of the user interface, and who can access the entire or part of that Org.
Metadata is made up of Metadata types, such as an apex class, or a custom object, and Metadata Components which is an instance of that Metadata Type.
Metadata API
Metadata API is a programmable interface to access Salesforce Metadata. The Metadata API works with metadata to move it between Orgs during development using the Metadata API deploy() and retrieve() calls. Often these calls are used to move the full metadata model. The Metatdata API allows complete metadata access to a Salesforce Org including the data model, business logic, and user interface.
For smaller changes, push and pull commands can be used to allow for smaller creation (createMetadata()) or deleting (deleteMetadata()) of metadata components. It is also possible to call a description of existing Metadata (describeMetadata()). In order to check for IDs for existing record types for example, the listMetatdata() call can be used.
Metadata API uses SOAP and supports both synchronous and asynchronous invocation. The synchronous calls are usually for immediate requests such as createMetadata(), and updateMetadata().
As well as passing Metadata information through .xml files, .zip files can be used with deploy() and retrieve() calls. The maximum size of a .zip file is 39 MB, when unzipped the size limit is 400 MB.
Tooling API
Tooling API is for smaller metadata tasks than the Metadata API – think fine-grained access. Smaller retrieves and deployments can be carried out with the Tooling API. An example here is using Workbench to fetch all Apex classes using the Tooling API.
It is possible to change just one element of a complex metadata type. Therefore this is an ideal API for continuous integration and Apex triggers and classes deployment.
Tooling API can use REST or SOAP and is synchronous. It’s possible to set the SOAP API calls to allow a call to roll back all changes if one element fails to process successfully.
Metadata API vs Tooling API?
Generally speaking, the Metadata API is for moving whole components whereas the Tooling API is for building them. The Metadata API is comparatively slow when compared to the fast Tooling API.