Newer Version Available

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

Step Two: Walk Through the Sample Code

Make a series of REST requests to try accessing different types of resources in Salesforce. Before you try these examples for yourself, make sure that you’ve completed the prerequisites and have obtained an access token in Step 1 of this quick start.

You can copy and paste these examples to send them with cURL. However, you must replace MyDomainName in the base URI with the domain for your Salesforce org. If you’re unfamiliar with the anatomy of a REST request, see REST Resources and Requests.

In this example, a series of REST requests is used in this 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. Submit a Versions request. In this case, the request doesn’t require authentication.

1curl https://MyDomainName.my.salesforce.com/services/data/

Here’s the output from this request, including the response header. The output specifies all valid versions (your result can include more than one value).

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

Next, use one of these versions to discover the resources it contains.

Get a List of Resources

Retrieve a list of the resources available for Salesforce, in this example, for version 54.0. Submit a Resources by Version request.

1curl https://MyDomainName.my.salesforce.com/services/data/v54.0/ -H "Authorization: Bearer access_token" -H "X-PrettyPrint:1"

Here’s the output from this request. You can see that sobjects is one of the available resources in Salesforce version 54.0.

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

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. Submit a Describe Global request.

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

Here’s the output from this request. You can see that the Account object is available.

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/v54.0/sobjects/Account",
18    "describe" : "/services/data/v54.0/sobjects/Account/describe",
19    "rowTemplate" : "/services/data/v54.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...

You can get more information about the Account object in the next steps.

Get Basic Object Information

Now that you’ve identified the Account object as an available resource, you can retrieve some basic information about its metadata. Submit a sObject Basic Information request.

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

Here’s the output from this request. You can see some basic attributes of the Account object, such as its name and label, and a list of the most recently used accounts.

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/v54.0/sobjects/Account/001D000000INjVeIAL"  
23            },  
24            "Id" : "001D000000INjVeIAL",  
25            "Name" : "asdasdasd"
26        }, 
27
28        ...
29
30    ]
31}

The next step retrieves more detailed information about the fields in the Account object, such as field lengths and default values.

Get a List of Fields

Retrieve more detailed information by submitting a sObject Describe request.

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

Here’s the output from this request. You can see much more detailed information about the Account object, such as its field attributes and child relationships.

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://MyDomainName.my.salesforce.com/{ID}/e",  
22        "sobject" : "/services/data/v54.0/sobjects/Account",  
23        "uiDetailTemplate" : "https://MyDomainName.my.salesforce.com/{ID}",  
24        "describe" : "/services/data/v54.0/sobjects/Account/describe",  
25        "rowTemplate" : "/services/data/v54.0/sobjects/Account/{ID}",  
26        "uiNewRecord" : "https://MyDomainName.my.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}

Now you have enough information to construct useful queries and updates for the Account objects in your org, which you 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. Submit a Query request.

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

The output lists the available Account names, and each name’s preceding attributes include the Account IDs.

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

In the next step, you 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

Retrieve one of the accounts and update its billing city by submitting an sObject Rows request. To update the object, create a text file called patchaccount.json containing the new billing city 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://MyDomainName.my.salesforce.com/services/data/v54.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 to see that the billing address has changed to Fremont.

REST API Developer Guide