Skip Navigation

Newer Version Available

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

Step Four: Walk Through the Sample Code

In this section you will create a series of REST requests. cURL will be used to construct the requests, and JSON will be used as the format for all requests and responses.

In each request, a base URI will be used in conjunction with the REST resource. The base URI for these examples is https://na1.salesforce.com/services/data. For more information, see Understanding Force.com REST Resources.

In this example, a series of REST requests will be used in the following scenario:

Get the Salesforce version.
Use the Salesforce version to get a list of the resources available.
Use one of the resources to get a list of the available objects.
Select one of the objects and get a description of its metadata.
Get a list of fields on that same object.
Execute a SOQL query to retrieve values from all name fields on Account records.
Update the Billing City for one of the Account objects.

Get the Salesforce Version

Begin by retrieving information about each available Salesforce version. To do this, submit a request for the Versions resource. In this case the request does not require authentication:

1curl https://na1.salesforce.com/services/data/

The output from this request, including the response header:

1Content-Length: 88 
2Content-Type: application/json; 
3charset=UTF-8 Server:
4[
5    {
6        "version":"20.0",
7        "url":"/services/data/v20.0",
8        "label":"Winter '11"
9    }
10    ...
11]

The output specifies the resources available for all valid versions (your result may include more than one value). Next, use one of these versions to discover the resources it contains.

Get a List of Resources

The next step is to retrieve a list of the resources available for Salesforce, in this example for version 20.0. To do this, submit a request for the Resources by Version:

1curl https://na1.salesforce.com/services/data/v20.0/ -H "Authorization: Bearer access_token" -H "X-PrettyPrint:1"

The output from this request is as follows:

1{
2    "sobjects" : "/services/data/v20.0/sobjects",
3    "search" : "/services/data/v20.0/search",
4    "query" : "/services/data/v20.0/query",
5    "recent" : "/services/data/v20.0/recent"
6}

From this output you can see that sobjects is one of the available resources in Salesforce version 20.0. You will be able to use this resource in the next request to retrieve the available objects.

Get a List of Available Objects

Now that you have the list of available resources, you can request a list of the available objects. To do this, submit a request for the Describe Global:

1curl https://na1.salesforce.com/services/data/v20.0/sobjects/ -H "Authorization: Bearer access_token" -H "X-PrettyPrint:1"

The output from this request is as follows:

1Transfer-Encoding: chunked 
2Content-Type: application/json; 
3charset=UTF-8 Server:
4{
5 "encoding" : "UTF-8",
6 "maxBatchSize" : 200,
7 "sobjects" : [ {
8    "name" : "Account",
9    "label" : "Account",
10    "custom" : false,
11    "keyPrefix" : "001",
12    "updateable" : true,
13    "searchable" : true,
14    "labelPlural" : "Accounts",
15    "layoutable" : true,
16    "activateable" : false,
17    "urls" : { "sobject" : "/services/data/v20.0/sobjects/Account",
18    "describe" : "/services/data/v20.0/sobjects/Account/describe",
19    "rowTemplate" : "/services/data/v20.0/sobjects/Account/{ID}" },
20    "createable" : true,
21    "customSetting" : false,
22    "deletable" : true,
23    "deprecatedAndHidden" : false,
24    "feedEnabled" : false,
25    "mergeable" : true,
26    "queryable" : true,
27    "replicateable" : true,
28    "retrieveable" : true,
29    "undeletable" : true,
30    "triggerable" : true },
31   },
32...

From this output you can see that the Account object is available. You will be able to get more information about the Account object in the next steps.

Get Basic Object Information

Now that you have identified the Account object as an available resource, you can retrieve some basic information about its metadata. To do this, submit a request for the SObject Basic Information:

1curl https://na1.salesforce.com/services/data/v20.0/sobjects/Account/ -H "Authorization: Bearer access_token" -H "X-PrettyPrint:1"

The output from this request is as follows:

1{
2    "objectDescribe" : 
3    {  
4        "name" : "Account",  
5        "updateable" : true,  
6        "label" : "Account",  
7        "keyPrefix" : "001",  
8        
9        ...
10        
11        "replicateable" : true,  
12        "retrieveable" : true,  
13        "undeletable" : true,  
14        "triggerable" : true
15    },
16    "recentItems" : 
17    [ 
18        {  
19            "attributes" : 
20            {    
21                "type" : "Account",    
22                "url" : "/services/data/v20.0/sobjects/Account/001D000000INjVeIAL"  
23            },  
24            "Id" : "001D000000INjVeIAL",  
25            "Name" : "asdasdasd"
26        }, 
27
28        ...
29
30    ]
31}

From this output you can see some basic attributes of the Account object, such as its name and label, as well as a list of the most recently used Accounts. Since you may need more information about its fields, such as length and default values, in the next step you will retrieve more detailed information about the Account object.

Get a List of Fields

Now that you have some basic information about the Account object's metadata, you may be interested in retrieving more detailed information. To do this, submit a request for the SObject Describe:

1curl https://na1.salesforce.com/services/data/v20.0/sobjects/Account/describe/ -H "Authorization: Bearer access_token" -H "X-PrettyPrint:1"

The output from this request is as follows:

1{
2    "name" : "Account",
3    "fields" : 
4    [
5        {
6            "length" : 18,
7            "name" : "Id",
8            "type" : "id",
9            "defaultValue" : { "value" : null },
10            "updateable" : false,
11            "label" : "Account ID",
12            ...
13        },
14        ...
15    ],
16    "updateable" : true,
17    "label" : "Account",
18    ...
19    "urls" : 
20    {  
21        "uiEditTemplate" : "https://na1.salesforce.com/{ID}/e",  
22        "sobject" : "/services/data/v20.0/sobjects/Account",  
23        "uiDetailTemplate" : "https://na1.soma.salesforce.com/{ID}",  
24        "describe" : "/services/data/v20.0/sobjects/Account/describe",  
25        "rowTemplate" : "/services/data/v20.0/sobjects/Account/{ID}",  
26        "uiNewRecord" : "https://na1.salesforce.com/001/e"
27    },
28    "childRelationships" : 
29    [ 
30        {  
31            "field" : "ParentId",  
32            "deprecatedAndHidden" : false,  
33            ...
34        }, 
35        ...
36    ],
37     
38    "createable" : true,
39    "customSetting" : false,
40    ...
41}

From this output you can see much more detailed information about the Account object, such as its field attributes and child relationships. Now you have enough information to construct useful queries and updates for the Account objects in your organization, which you will do in the next steps.

Execute a SOQL Query

Now that you know the field names on the Account object, you can execute a SOQL query, for example, to retrieve a list of all the Account name values. To do this, submit a Query request:

1curl https://na1.salesforce.com/services/data/v20.0/query?q=SELECT+name+from+Account -H "Authorization: Bearer access_token" -H "X-PrettyPrint:1"

The output from this request is as follows:

1{
2    "done" : true,
3    "totalSize" : 14,
4    "records" :
5    [
6        {
7            "attributes" :
8            {
9                "type" : "Account",
10                "url" : "/services/data/v20.0/sobjects/Account/001D000000IRFmaIAH"
11            },
12            "Name" : "Test 1"
13        },
14        {
15            "attributes" :
16            {
17                "type" : "Account",
18                "url" : "/services/data/v20.0/sobjects/Account/001D000000IomazIAB"
19            },
20            "Name" : "Test 2"
21        },
22        ...
23    ]
24}

From this output you have a listing of the available Account names, and each name's preceding attributes include the Account IDs. In the next step you will use this information to update one of the accounts.

You can find more information about SOQL in the Salesforce SOQL and SOSL Reference Guide.

Note

Update a Field on a Record

Now that you have the Account names and IDs, you can retrieve one of the accounts and update its Billing City. To do this, you will need to submit an SObject Rows request. To update the object, supply the new information about the Billing City. Create a text file called patchaccount.json containing the following information:

1{
2    "BillingCity" : "Fremont"
3}

Specify this JSON file in the REST request. The cURL notation requires the —d option when specifying data. For more information, see http://curl.haxx.se/docs/manpage.html.

Also, specify the PATCH method, which is used for updating a REST resource. The following cURL command retrieves the specified Account object using its ID field, and updates its Billing City.

1curl https://na1.salesforce.com/services/data/v20.0/sobjects/Account/001D000000IroHJ -H "Authorization: Bearer access_token" -H "X-PrettyPrint:1" -H "Content-Type: application/json" --data-binary @patchaccount.json -X PATCH

No response body is returned, just the headers:

1HTTP/1.1 204 No Content
2Server: 
3Content-Length: 0

Refresh the page on the account and you will see that the Billing Address has changed to Fremont.

Other Resources

Search for Ruby on developer.salesforce.com
Force.com Cookbook recipe for getting started in Ruby
Force.com REST API Board