Force.com Tooling API

Introducing Tooling API
When to Use Tooling API
REST Resources
SOAP Calls
Objects, Namespaces, and Tooling API
Tooling API Objects
SOAP Headers for Tooling API
Rest Headers for Tooling API
PDF

Newer Version Available

This content describes an older version of this product. View Latest

REST Resources

Use REST if you’re using a language that isn’t strongly typed, like JavaScript.

REST Resources

For details on usage, syntax, and authentication, see the Force.com REST API Developer's Guide.

This section lists supported REST resources in Tooling API.

The base URI for each Tooling REST API resource is http://domain/services/data/vXX.X/tooling/ where domain is a Salesforce instance or a custom domain and vXX.X is the API version number. For example: http://na1.salesforce.com/services/data/v35.0/tooling/

Like the Force.com REST API, Tooling API uses the following resources.

/completions?type=
Supported methods: GET
Retrieves available code completions of the referenced type for Apex system method symbols (type=apex). Available from API version 28.0 or later.
/executeAnonymous/?anonymousBody= <url encoded body>
Supported methods: GET
Executes Apex code anonymously. Available from API version 29.0 or later.
/query/?q=SOQL_Query_Statement
Supported methods: GET
Executes a query against an object and returns data that matches the specified criteria. Tooling API exposes objects like EntityDefinition and FieldDefinition that use the external object framework--that is, they don’t exist in the database but are constructed dynamically. Special query rules apply to virtual entities.

If the query result is too large, it’s broken up into batches. The response contains the first batch of results and a query identifier. The identifier can be used in a request to retrieve the next batch.

/runTestsAsynchronous/?classids= <comma separated list of class IDs>
Supported methods: GET
Executes the tests in the specified classes. Running tests asynchronously allows methods to process in parallel, cutting down your test run times.
/runTestsAsynchronous/ Body: {"classids":"<comma-separated list of class IDs>"} or
/runTestsAsynchronous/ Body: {"tests":<tests array>}
Supported methods: POST

Runs one or more methods within one or more Apex classes, using the asynchronous test execution mechanism.

<tests array> is an array of objects, each with two parameters:
  • classId—A String containing a test class ID. Each class ID can be listed only once.
  • testMethods—An array of Strings where each string represents the name of a test method in the test class specified by classId.

    Multiple occurrences of a test method name in a testMethods array are ignored. Test methods that don’t exist are skipped. A null or missing testMethods array specifies that all test methods in the test class are run.

Example <tests array>:
1[{
2"classId" : "yourClassId",
3"testMethods" : ["testMethod1","testMethod2","testMethod3"]
4},{
5"classId" : "yourOtherClassId",
6"testMethods" : ["testMethod1","testMethod2"]
7}]
/runTestsSynchronous/?classnames= <comma-separated list of class names>
Supported methods: GET
Executes the tests in the specified classes using the synchronous test execution mechanism.
/runTestsSynchronous/ Body: {"tests":<tests array>}
Supported methods: POST

Runs one or more methods within an Apex class, using the synchronous test execution mechanism. All test methods in a synchronous test run must be in the same class.

<tests array> is an array of objects, each with two parameters:
  • classId—A String containing a test class’s ID.
  • testMethods—An array of Strings, each containing the name of a test method in the test class.

    Multiple occurrences of a test method name in a testMethods array are ignored. Test methods that don’t exist are skipped. A null or missing testMethods array specifies that all test methods in the test class are run.

Example <tests array>:
1[{
2"classId" : "yourClassId",
3"testMethods" : ["testMethod1","testMethod2","testMethod3"]
4}]
/search/?q=SOSL_Search_Statement
Supported methods: GET
Search for records containing specified values.
/sobjects/
Supported methods: GET
Lists the available Tooling API objects and their metadata.
/sobjects/SObjectName/
Supported methods: GET, POST
Describes the individual metadata for the specified object or creates a record for a given object.
  • To retrieve the metadata for the ApexExecutionOverlayAction object, use the GET method.
  • To create a ApexExecutionOverlayAction object, use the POST method.
/sobjects/SObjectName/describe/
Supported methods: GET
Completely describes the individual metadata at all levels for the specified object.

For example, use this resource to retrieve the fields, URLs, and child relationships for a Tooling API object.

/sobjects/SObjectName/id/
Supported methods: GET, PATCH, DELETE
Accesses records based on the specified object ID.

Use the GET method to retrieve records or fields, the DELETE method to delete records, and the PATCH method to update records.

/sobjects/ApexLog/id/Body/
Supported methods: GET
Retrieves a raw debug log by ID. Available from API version 28.0 or later.

REST Headers

REST headers available in the Tooling API WSDL are described in Rest Headers for Tooling API.

Examples

The following examples use Apex to execute REST requests, but you can use any standard REST tool to access Tooling REST API.

Salesforce runs on multiple server instances. The examples in this guide use the na1 instance. Be sure to use your organization’s instance name.

Note

First, set up the connection to your org and the HTTP request type:
1HttpRequest req = new HttpRequest();
2req.setHeader('Authorization', 'Bearer ' + UserInfo.getSessionID());
3req.setHeader('Content-Type', 'application/json');
At the end of each request, add the following code to send the request and retrieve the body of the response:
1Http h = new Http();
2HttpResponse res = h.send(req);
3system.debug(res.getBody());
To get a description of all available objects in Tooling API: 
1req.setEndpoint('http://na1.salesforce.com/services/data/v28.0/tooling/sobjects/');
2req.setMethod('GET');
To get a description of a specific Tooling API object, for example TraceFlag:
1req.setEndpoint('http://na1.salesforce.com/services/data/v28.0/tooling/sobjects/
2TraceFlag/');
3req.setMethod('GET');
To get a description of all the metadata for a specific Tooling API object, for example TraceFlag:
1req.setEndpoint('http://na1.salesforce.com/services/data/v28.0/tooling/sobjects/
2TraceFlag/describe/');
3req.setMethod('GET');
To create a new Tooling API object, for example MetadataContainer:
1req.setEndpoint('http://na1.salesforce.com/services/data/v28.0/tooling/sobjects/
2MetadataContainer/');
3req.setBody('{"Name":"TestContainer"}');
4req.setMethod('POST');

Use the ID from this call in the rest of the examples.

Tip

To retrieve a Tooling API object by ID, for example MetadataContainer: 
1req.setEndpoint('http://na1.salesforce.com/services/data/v28.0/tooling/sobjects/
2MetadataContainer/ + containerID + '/'); 
3req.setMethod('GET');
To update a Tooling API object by ID, for example MetadataContainer: 
1req.setEndpoint('http://na1.salesforce.com/services/data/v28.0/tooling/sobjects/
2MetadataContainer/ + containerID + '/');
3req.setBody('{"Name":"NewlyNamedContainer"}');
4req.setMethod('PATCH');
To query a Tooling API object by ID, for example MetadataContainer: 
1req.setEndpoint('http://na1.salesforce.com/services/data/v28.0/tooling/query/?q=
2Select+id,Name+from+MetadataContainer+Where+ID=\'' + containerID +  '\'');
3req.setMethod('GET');
To query an object within a MetadataContainer:
1req.setEndpoint('http://na1.salesforce.com/services/data/v28.0/tooling/query/?q=
2Select+id,Body,LastSyncDate,Metadata+from+ApexClassMember+Where+MetadataContainerID=\' 
3+ containerID +  '\'');
4req.setMethod('GET');
To check on the status of a deployment, using ContainerAsyncRequest:
1req.setEndpoint('http://na1.salesforce.com/services/data/v28.0/tooling/sobjects/
2ContainerAsyncRequest/' + requestID + '/');
3req.setMethod('GET');

To execute anonymous Apex:

1req.setEndpoint('http://na1.salesforce.com/services/data/v28.0/tooling/executeAnonymous/?
2anonymousBody=System.debug('Test')%3B');
3req.setMethod('GET');

To retrieve your Apex classes and triggers, and the global Apex classes and triggers from your installed managed packages:

1req.setEndpoint('http://na1.salesforce.com/services/data/v33.0/tooling/apexManifest');
2req.setMethod('GET');