Force.com REST API Walk-Through
Now that you have obtained an OAuth access token, you are ready to try the Force.com REST API. Set the access token as the environment variable $TOKEN. Also, be sure to replace na15 in the following examples with your own instance of Force.com. To identify your instance, look at the instance_url field of the OAuth username-password flow, or the URL in your Web browser when you log in to Force.com.
Note
This section is not a complete reference to the REST API. Consult the Force.com REST API Developer’s Guide, found at www.salesforce.com/us/developer/docs/api_rest/index.htm, for the latest and most detailed information on the REST API, which Salesforce continuously improves in each major release of the platform.
Listing 10.5 is an example of one of the simplest REST API calls. It returns the services available via REST in the specified version and instance of the Force.com platform. Here, the result indicates four services. In subsequent examples, you’ll try all the services, except recent. The recent service returns the same data as you see in the Recent Items box in the Web user interface.
Listing 10.5 Services Available Request and Response
curl https://na15.salesforce.com/services/data/v28.0
-H "Authorization: OAuth "$TOKEN -H "X-PrettyPrint:1"
{
"sobjects" : "/services/data/v28.0/sobjects",
"identity" : "https://login.salesforce.com/id/... ",
"connect" : "/services/data/v28.0/connect",
"search" : "/services/data/v28.0/search",
"quickActions" : "/services/data/v28.0/quickActions",
"query" : "/services/data/v28.0/query",
"tooling" : "/services/data/v28.0/tooling",
"chatter" : "/services/data/v28.0/chatter",
"recent" : "/services/data/v28.0/recent"
}
Tip
The backslash () character found at the end of the first line in Listing 10.5 and other listings in this chapter is a line-continuation character for UNIX shells. Translate it as appropriate to your own command-line environment.
To retrieve basic information on an SObject, use the sobjects service, as demonstrated in Listing 10.6. You can also omit the object name (/Project__c) to get a list of all SObjects, or append /describe to the end of the URL to obtain the full, detailed list of fields on the SObject. If an error occurs in processing this request or any REST request, the response contains message and errorCode keys to communicate the error message and code.
Listing 10.6 Basic Information Request for an SObject
curl https://na15.salesforce.com/services/data/v28.0/sobjects/Project__c
-H "Authorization: OAuth "$TOKEN -H "X-PrettyPrint:1"
Another usage of the sobjects service is shown in Listing 10.7. Here an individual record is returned, identified by its unique identifier. The fields parameter specifies a subset of fields to return. You can omit this parameter to retrieve all fields. If your record is a binary object such as a Document, append /body to the URL to retrieve the binary content.
Listing 10.7 Record Retrieval by Unique Identifier Request and Response
curl https://na15.salesforce.com/services/data/v28.0
/sobjects/Project__c/a01i0000000rMq1?fields=Name,Status__c
-H "Authorization: OAuth "$TOKEN -H "X-PrettyPrint:1"
{
"attributes" : {
"type" : "Project__c",
"url" : "/services/data/v20.0/sobjects/Proj__c/a01i0000000rMq1AAE"
},
"Name" : "GenePoint",
"Status__c" : "Green",
"Id" : "a01i0000000rMq1AAE"
}
Listing 10.8 demonstrates record retrieval by external identifier. The record with a Project_ID__c value of Project-00001 on the Project__c SObject is returned.
Listing 10.8 Request for Retrieval of Record by External Identifier
curl https://na15.salesforce.com/services/data/v28.0
/sobjects/Project__c/Project_ID__c/Project-00001
-H "Authorization: OAuth "$TOKEN -H "X-PrettyPrint:1"
A simple SOQL query is shown in Listing 10.9. To run a SOSL query, use search instead of query in the URL.
Listing 10.9 SOQL Query Request
curl https://na15.salesforce.com/services/data/v28.0
/query?q=SELECT+Name+FROM+Project__c
-H "Authorization: OAuth "$TOKEN -H "X-PrettyPrint:1"
To create a record, make a POST request with the SObject type in the URL and a JSON or XML request body containing the record’s field values. Listing 10.10 creates a new Project__c record named Test Project. A successful response provides the new record’s unique identifier.
Listing 10.10 Create Record Request and Response
echo '{ "Name": "Test Project" }' |
curl -X POST -H 'Content-type: application/json'
-H "Authorization: OAuth "$TOKEN -H "X-PrettyPrint:1" -d @-
https://na15.salesforce.com/services/data/v28.0/sobjects/Project__c
{
"id" : "a01i0000003aFzrAAE",
"success" : true,
"errors" : [ ]
}
Tip
To adapt the command in Listing 10.10 to run in Windows Command Prompt, remove the single quotation mark characters (') in the echo statement, replace the single quotation mark characters around the Content-type header with double quotation mark characters ("), remove the backslash () line-continuation characters and concatenate the lines into a single line, and replace $TOKEN with _KEN%.
Updating a record follows a similar process to creating a record. Make a PATCH request with the URL containing the SObject type and unique identifier, and a request body with the field values to update. In Listing 10.11, the record created in Listing 10.10 gets its name updated.
Listing 10.11 Update Record Request
echo '{ "Name": "Updated Test Project" }' |
curl -X PATCH -H 'Content-type: application/json'
-H 'Authorization: OAuth '$TOKEN -H "X-PrettyPrint:1" -d @-
https://na15.salesforce.com/services/data/v28.0
/sobjects/Project__c/a01i0000003aFzrAAE
The only difference between an upsert and update request is that upsert uses an external identifier rather than the unique identifier. If the external identifier value is not found, the request creates the record and its unique identifier is returned. Otherwise, the record is updated, and nothing is returned upon success. Listing 10.12 demonstrates an upsert of a Project__c record.
Note
Listing 10.12 will return an INVALID_FIELD_FOR_INSERT_UPDATE error unless you change the Project_ID__c field type from Auto Number to Text first because Auto Number fields are read-only.
Listing 10.12 Upsert Record Request and Response
echo '{ "Name": "Upserted Project" }' |
curl -X PATCH -H 'Content-type: application/json'
-H "Authorization: OAuth "$TOKEN -H "X-PrettyPrint:1" -d @-
https://na15.salesforce.com/services/data/v28.0
/sobjects/Project__c/Project_ID__c/Project-11111
Deleting a record by its unique identifier is shown in Listing 10.13. You can also delete a record by its external identifier. In both cases, nothing is returned by a successful request.
Listing 10.13 Delete Record Request
curl -X DELETE
-H 'Authorization: OAuth '$TOKEN -H "X-PrettyPrint:1"
https://na15.salesforce.com/services/data/v28.0
/sobjects/Project__c/a01i0000003aFzrAAE