Force.com Tooling API

Introducing Tooling API
When to Use Tooling API
REST Overview
REST Resources
REST Resource Examples
REST Headers
REST Header Examples
SOAP Calls
Tooling API Objects and Namespaces
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

REST Resources give you access to Tooling API objects. To query Tooling API objects using REST resources, you need the “View All Data” user permission.

REST Resources Supported by Tooling API

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

For examples, see REST Resource Examples.

The base URI for each Tooling API REST 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: https://yourInstance.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/ and /runTestsSynchronous/
Resource API Version 36.0 and Earlier API Version 37.0 and Later
/runTestsAsynchronous/: GET

Executes the tests in the specified classes. Running tests asynchronously allows methods to process in parallel, cutting down your test run times.

 Not supported.
/runTestsAsynchronous/: POST with comma-separated lists
  • Runs one or more methods within one or more Apex classes, using the asynchronous test execution mechanism.
  • You can POST both a suiteids list and a classids list to runTestsAsynchronous. However, if you send a tests array, you can’t send suiteids or classids.
  • You can also POST an optional maxFailedTests parameter. To allow all tests in your run to execute, regardless of how many tests fail, omit maxFailedTests or set it to -1. To stop the test run from executing new tests after a given number of tests fail, set maxFailedTests to an integer value from 0 to 1,000,000. This integer value sets the maximum allowable test failures. A value of 0 causes the test run to stop if any failure occurs. A value of 1 causes the test run to stop on the second failure, and so on. Keep in mind that high values can cause slow performance. Each 1,000 tests that you add to your maxFailedTests value adds about 3 seconds to your test run, not including the time that the tests take to execute.
  • Runs one or more methods within one or more Apex classes, using the asynchronous test execution mechanism.
  • You can POST both a suiteids list and a classids list to runTestsAsynchronous. However, if you send a tests array, you can’t send suiteids or classids.
  • You can also POST an optional maxFailedTests parameter. To allow all tests in your run to execute, regardless of how many tests fail, omit maxFailedTests or set it to -1. To stop the test run from executing new tests after a given number of tests fail, set maxFailedTests to an integer value from 0 to 1,000,000. This integer value sets the maximum allowable test failures. A value of 0 causes the test run to stop if any failure occurs. A value of 1 causes the test run to stop on the second failure, and so on. Keep in mind that high values can cause slow performance. Each 1,000 tests that you add to your maxFailedTests value adds about 3 seconds to your test run, not including the time that the tests take to execute.

  • The testLevel parameter is optional. If you don’t provide a testLevel value, we use RunSpecifiedTests.

    Permissible values include:
    RunSpecifiedTests
    Only the tests that you specify are run.
    RunLocalTests
    All tests in your org are run, except the ones that originate from installed managed packages.
    Omit identifiers for specific tests when you use this value.
    RunAllTestsInOrg
    All tests are run. The tests include all tests in your org, including tests of managed packages.
    Omit identifiers for specific tests when you use this value.
/runTestsAsynchronous/: POST with JSON
Example <tests array>:
  • Runs one or more methods within one or more Apex classes, using the asynchronous test execution mechanism.
  • <tests array> is an array of objects that represent Apex test classes, each of which has a classId and a testMethods parameter, and an optional maxFailedTests parameter.
  • 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.
  • To allow all tests in your run to execute, regardless of how many tests fail, omit maxFailedTests or set it to -1. To stop the test run from executing new tests after a given number of tests fail, set maxFailedTests to an integer value from 0 to 1,000,000. This integer value sets the maximum allowable test failures. A value of 0 causes the test run to stop if any failure occurs. A value of 1 causes the test run to stop on the second failure, and so on. Keep in mind that high values can cause slow performance. Each 1,000 tests that you add to your maxFailedTests value adds about 3 seconds to your test run, not including the time that the tests take to execute.
Example <tests array>:
  • Runs one or more methods within one or more Apex classes, using the asynchronous test execution mechanism.
  • <tests array> is an array of objects that represent Apex test classes—each of which has a classId and a testMethods parameter. The tests array also includes an optional maxFailedTests parameter and a required testLevel parameter.
  • 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
  • To allow all tests in your run to execute, regardless of how many tests fail, omit maxFailedTests or set it to -1. To stop the test run from executing new tests after a given number of tests fail, set maxFailedTests to an integer value from 0 to 1,000,000. This integer value sets the maximum allowable test failures. A value of 0 causes the test run to stop if any failure occurs. A value of 1 causes the test run to stop on the second failure, and so on. Keep in mind that high values can cause slow performance. Each 1,000 tests that you add to your maxFailedTests value adds about 3 seconds to your test run, not including the time that the tests take to execute.

  • The testLevel parameter is optional. If you don’t provide a testLevel value, we use RunSpecifiedTests.

    Permissible values include:
    RunSpecifiedTests
    Only the tests that you specify are run.
    RunLocalTests
    All tests in your org are run, except the ones that originate from installed managed packages.
    Omit identifiers for specific tests when you use this value.
    RunAllTestsInOrg
    All tests are run. The tests include all tests in your org, including tests of managed packages.
    Omit identifiers for specific tests when you use this value.
/runTestsSynchronous/: GET

Executes the tests in the specified classes using the synchronous test execution mechanism.

 Not supported.
/runTestsSynchronous/: POST
Example <tests array>:
  • 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 an object that represents an Apex test class—which has a classId and a testMethods parameter—and an optional maxFailedTests parameter.
  • 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
  • To allow all tests in your run to execute, regardless of how many tests fail, omit maxFailedTests or set it to -1. To stop the test run from executing new tests after a given number of tests fail, set maxFailedTests to an integer value from 0 to 1,000,000. This integer value sets the maximum allowable test failures. A value of 0 causes the test run to stop if any failure occurs. A value of 1 causes the test run to stop on the second failure, and so on. Keep in mind that high values can cause slow performance. Each 1,000 tests that you add to your maxFailedTests value adds about 3 seconds to your test run, not including the time that the tests take to execute.
Example <tests array>:
  • 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 an object that represents an Apex test class—which has a classId and a testMethods parameter—and an optional maxFailedTests parameter.
  • 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
  • To allow all tests in your run to execute, regardless of how many tests fail, omit maxFailedTests or set it to -1. To stop the test run from executing new tests after a given number of tests fail, set maxFailedTests to an integer value from 0 to 1,000,000. This integer value sets the maximum allowable test failures. A value of 0 causes the test run to stop if any failure occurs. A value of 1 causes the test run to stop on the second failure, and so on. Keep in mind that high values can cause slow performance. Each 1,000 tests that you add to your maxFailedTests value adds about 3 seconds to your test run, not including the time that the tests take to execute.
/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.