REST
How to call salesforce.com using REST
Inspired by the Quickstart
Requirements
Your salesforce org
UNIX shell with cURL command
Legend
Text you will edit
Three Easy Steps
1) Replace na9 below with your instance.
2) Authenticate via Workbench for your session:
Workbench > Login > Info > Session Info > Connection > Session Id
Use that in <session ID> below.
3) Run these examples in your shell:
Basic examples
# List available versions of the REST API
curl https://na9.salesforce.com/services/data/ \
-H 'Authorization: Bearer <session ID>' \
-H "X-PrettyPrint:1"
# List all custom objects and fields
curl https://na9.salesforce.com/services/data/v26.0/sobjects \
-H 'Authorization: Bearer <session ID>' \
-H 'X-PrettyPrint:1' \
| grep name | grep __c
Chatter examples
# List all users in this org
curl https://na9.salesforce.com/services/data/v26.0/chatter/users \
-H 'Authorization: Bearer <session ID>' \
-H 'X-PrettyPrint:1' \
| grep name
# List all groups in this org
curl https://na9.salesforce.com/services/data/v26.0/chatter/groups \
-H 'Authorization: Bearer <session ID>' \
-H 'X-PrettyPrint:1' \
| grep name
# Who am I?
curl https://na9.salesforce.com/services/data/v26.0/chatter/users/me \
-H 'Authorization: Bearer <session ID>' \
-H 'X-PrettyPrint:1' \
| grep name
# My groups
curl https://na9.salesforce.com/services/data/v26.0/chatter/users/me/groups \
-H 'Authorization: Bearer <session ID>' \
-H 'X-PrettyPrint:1' \
| grep name
# Update my status
curl https://na9.salesforce.com/services/data/v26.0/chatter/feeds/news/me/feed-items?text=Posted+using+REST+API \
-H 'Authorization: Bearer <session ID>' \
-H 'X-PrettyPrint:1' -X POST
Retrieval and Description examples
(Assumes your data model includes a custom object Job__c with textual field status__c. Season to taste)
# Retrieve all records in one object (here the custom object Job__c):
curl https://na9.salesforce.com/services/data/v26.0/query?q=SELECT+Name+FROM+Job__c \
-H 'Authorization: Bearer <session ID>' \
-H "X-PrettyPrint:1"
# Describe an object (Job__c):
curl https://na9.salesforce.com/services/data/v26.0/sobjects/Job__c/describe/ \
-H 'Authorization: Bearer <session ID>' \
-H 'X-PrettyPrint:1'
# Inspect a record (replace literal Id below with your actual record Id)
curl https://na9.salesforce.com/services/data/v26.0/sobjects/Job__c/a0OE0000000TjF7/ \
-H 'Authorization: Bearer <session ID>' \
-H "X-PrettyPrint:1"
DML examples
Step 1: Prepare source data files:
Create a file (NewRecord.json)containing one record to be added to our object Job__c:
{ "Name" : "Java Janitor" }
Create a file (PatchRecord.json) containing an updated field to be applied to a record:
{ "Status__c" : "Closed" }
Step 2: Create or Update a record:
# Insert from source data file (above):
curl https://na9.salesforce.com/services/data/v26.0/sobjects/Job__c/ \
-H "Content-Type: application/json" -d @NewRecord.json \
-H 'Authorization: Bearer <session ID>' \
-H "X-PrettyPrint:1"
# Update a record. Replace the literal Id below with your actual Id of the record to be replaced:
curl https://na9.salesforce.com/services/data/v26.0/sobjects/Job__c/a0OE0000000TjF7 \
-H 'Authorization: Bearer <session ID>' \
-H "Content-Type: application/json" --data-binary @PatchRecord.json -X PATCH \
-H "X-PrettyPrint:1"
Authored by Matthew Reiser, 2013. Your feedback is always welcome.