INTEGRATION

Force.com REST API Cheat Sheet

Overview
The Force.com REST API provides you with a powerful Web services API that you can use to interact with Force.com.
Each resource in REST API is a named URI that's used with an HTTP method: HEAD, GET, POST, PATCH, or DELETE. All resources are accessed using a generic interface over
HTTP with a base URI that follows your Force.com or Database.com URI. REST API supports authentication using OAuth 2.0 and supports both JSON and XML ( JSON is the default).

REST Requests
Action

URL

HTTP Method

Request Body

Create

https://instance.salesforce.com/services/data/vNN.N/sobjects/

POST

field-value pairs

Delete

https://instance.salesforce.com/services/data/vNN.N/sobjects/Obj/Id

DELETE

N/A

Update

https://instance.salesforce.com/services/data/vNN.N/sobjects/Obj/Id

PATCH

field-value pairs

Upsert

https://instance.salesforce.com/services/data/vNN.N/sobjects/Obj/externalIdField/value

PATCH

field-value pairs

SOQL Query

https://instance.salesforce.com/services/data/vNN.N/query/?q=soqlQuery

GET

N/A

SOSL Search

https://instance.salesforce.com/services/data/vNN.N/search/?q=soslQuery

GET

N/A

Describe

https://instance.salesforce.com/services/data/vNN.N/sobjects/

GET

N/A

Describe SObject

https://instance.salesforce.com/services/data/vNN.N/sobjects/Obj

GET

N/A

HTTP requests to a REST API resource should contain the following information:
An HTTP method (HEAD, GET, POST, PATCH, or DELETE).
A session ID or an OAuth 2.0 access token used to authenticate the request.
An HTTP ACCEPT header that indicates the resource format ( JSON or XML), or a .json or .xml extension to the URI. The default is JSON.
The Force.com or Database.com REST resource.
Any JSON or XML data containing information needed for the request, such as the data required when updating a record.

Resources
Resource Name

URI

Description

Versions

Lists summary information about each Salesforce version currently available, including
the version, label, and a link to each version's root.

Resources by Version

/vNN.N/

Lists available resources for the specified API version, including resource name and URI.

Describe Global

/vNN.N/sobjects/

Lists available objects and their metadata for your organization's data.

SObject Basic Information

/vNN.N/sobjects/SObject/

Describes the individual metadata for the specified object.

SObject Describe

/vNN.N/sobjects/SObject/describe

Completely describes the individual metadata at all levels for the specified object.

SObject Rows

/vNN.N/sobjects/SObject/id/

Accesses records based on the specified object ID. Retrieves, creates, updates, or
deletes records.

SObject Rows By External ID

/vNN.N/sobjects/SObjectName/fieldName/
fieldValue

Creates new records or updates existing records (upserts records) based on the
value of a specified external ID field.

SObject Blob Retrieve

/vNN.N/sobjects/SObject/id/blobField

Retrieves the specified blob field from an individual record.

Query

/vNN.N/query/?q=soqlQuery

Executes the specified SOQL query. The query string must be URL-encoded.

Search

/vNN.N/search/?s=soslQuery

Executes the specified SOSL search. The search string must be URL-encoded.

http://developer.salesforce.com

REST API Headers

REST API supports the following headers:
Header

Description

Example

Content-Type

Specifies whether the request is formatted as JSON or XML.

Content-Type: application/json

Authorization

Used to authenticate the request.

Authorization: OAuth sessionId

X-Pretty-Print

Formats the response in a more readable format with line breaks and
indentation.

X-PrettyPrint:1

Accept

Indicates the resource format which can be either JSON or XML.

Accept: application/xml

X-Sfdc-PackageVersionPackageName

Specifies the package version under which context an API call is made.

X-Sfdc-PackageVersion-MyPackage: 2.0

HTTP Error Codes

HTTP Success Codes

When errors occur, the response header contains an HTTP code, and the response body
typically contains the error code, the message accompanying that error, and the field or
object where the error occurred.

When a request is successful, the response header contains an HTTP code, and the response
body contains a Boolean success value.

300

400

The session ID or OAuth token used has expired or is invalid.

The response body contains the message and errorCode.

403

The request has been refused. Verify that the logged-in user has
appropriate permissions.

404

The requested resource could not be found. Check the URI for
errors, and verify that there are no sharing issues.

405

The method specified in the Request-Line is not allowed for the

resource specified in the URI.

500

The request has been successfully processed.

201

The request has been successfully processed and the resource has
been created.

204

The request has been successfully processed, but no content is

returned in the response body. This code is returned after a resource
is successfully deleted.

The request could not be understood, usually because the JSON

or XML body has an error.

401

415

200

The value used for an external ID exists in more than one record.
The response body contains the list of matching records.

The entity specified in the request is in a format that is not

supported by specified resource for the specified method.
An error has occurred within Force.com, so the request could not
be completed. Contact salesforce.com Customer Support.

HTTP Methods
REST API supports the following HTTP methods:
GET

Retrieves information, such as basic resource summary information.

HEAD

Retrieves resource metadata.

PATCH

Updates a record.

POST

Creates a new object.

DELETE

Deletes a record.

Examples
Following are some examples of calling REST API using cURL. Replace token with your session ID. Depending on your platform, if the token contains an exclamation mark (!),
it should be escaped with a backslash (\!) when used in cURL commands. Depending on your platform, request headers may require single quotes (') or double quotes (").

Create an Invoice Statement

cURL Command
curl https://instance.salesforce.com/services/data/v24.0/sobjects/Invoice_Statement__c/ -H "Content-Type:application/json" -d
"{\"Description__c\" : \"New invoice statement\"}" -H "Authorization: OAuth token" -H "X-PrettyPrint:1"

Response (JSON)
{
"id" : "a00D0000008oLd7IAE",
"errors" : [ ],
"success" : true
}

Update Status__c Field on an Invoice Statement

cURL Command
curl https://instance.salesforce.com/services/data/v24.0/sobjects/Invoice_Statement__c/a00D0000008o6yDIAQ -H "Authorization: OAuth
token" -H "Content-Type: application/json" -d "{\"Status__c\" : \"Open\"}" -X PATCH -H "X-PrettyPrint:1"

Response (JSON)
N/A

Delete an Invoice Statement

cURL Command
curl https://instance.salesforce.com/services/data/v24.0/sobjects/Invoice_Statement__c/a00D0000008oLd7IAE -H "Authorization: OAuth
token" -H "X-PrettyPrint:1" -X DELETE

Response (JSON)
N/A

Search for a String

cURL Command
curl https://instance.salesforce.com/services/data/v24.0/search/?q=FIND+%7Bcountry%7D -H "Authorization: OAuth token" -H
"X-PrettyPrint:1"

Response (JSON)
[ {
"attributes" : {
"type" : "Invoice_Statement__c",
"url" : "/services/data/v24.0/sobjects/Invoice_Statement__c/a00D0000008o6yDIAQ"
},
"Id" : "a00D0000008o6yDIAQ"
} ]

Execute a Query
cURL Command
curl https://instance.salesforce.com/services/data/v24.0/query?q=SELECT+Id,+Name,+Status__c+FROM+Invoice_Statement__c -H
"Authorization: OAuth token" -H "X-PrettyPrint:1"

Response (JSON)
{
"done" : true,
"totalSize" : 3,
"records" : [ {
"attributes" : {
"type" : "Invoice_Statement__c",
"url" : "/services/data/v24.0/sobjects/Invoice_Statement__c/a00D0000008o6y
3IAA"
},
"Id" : "a00D0000008o6y3IAA",
"Name" : "INV-0000",
"Status__c" : "Open"
}, {
"attributes" : {
"type" : "Invoice_Statement__c",
"url" : "/services/data/v24.0/sobjects/Invoice_Statement__c/a00D0000008o6y
DIAQ"
},
"Id" : "a00D0000008o6yDIAQ",
"Name" : "INV-0002",
"Status__c" : "Closed"
} ]
}

Get Basic Object Information for Invoice Statement

cURL Command
curl https://instance.salesforce.com/services/data/v24.0/sobjects/Invoice_Statement__c -H "Authorization: OAuth token" -H
"X-PrettyPrint:1"
Response (JSON)
{
"objectDescribe" : {
"name" : "Invoice_Statement__c",
"updateable" : true,
"keyPrefix" : "a00",
"label" : "Invoice Statement",
"custom" : true,
"urls" : {
"sobject" : "/services/data/v24.0/sobjects/Invoice_Statement__c",
"describe" : "/services/data/v24.0/sobjects/Invoice_Statement__c/describe",
"rowTemplate" : "/services/data/v24.0/sobjects/Invoice_Statement__c/{ID}"
},
"searchable" : true,
"labelPlural" : "Invoice Statements",
"layoutable" : true,
"activateable" : false,
"createable" : true,
"deprecatedAndHidden" : false,
"deletable" : true,
"customSetting" : false,
"feedEnabled" : false,
"mergeable" : false,
"queryable" : true,
"replicateable" : true,
"retrieveable" : true,
"undeletable" : true,
"triggerable" : true
},
"recentItems" : [ {
"attributes" : {
"type" : "Invoice_Statement__c",
"url" : "/services/data/v24.0/sobjects/Invoice_Statement__c/a00D0000008o6y8IAA"
},
"Id" : "a00D0000008o6y8IAA",
"Name" : "INV-0001"
}, {
"attributes" : {
"type" : "Invoice_Statement__c",
"url" : "/services/data/v24.0/sobjects/Invoice_Statement__c/a00D0000008o6yDIAQ"
},
"Id" : "a00D0000008o6yDIAQ",
"Name" : "INV-0002"
} ]
}

OAuth Username/Password Authentication

cURL Command
curl https://login.salesforce.com/services/oauth2/token -d 'grant_type=password&client_id=REMOTE_ACCESS_CLIENT_ID&client_
secret=REMOTE_ACCESS_CLIENT_SECRET&[email protected]&password=********' -H "X-PrettyPrint: 1"

Response (JSON)
{
"id" : "https://login.salesforce.com/id/00D50000000IZ3ZEAW/00550000001fg5OAAQ",
"issued_at" : "1322006414073",
"instance_url" : "https://instance.salesforce.com",
"signature" : "3/FtJxcTxvpwJx8Tloc/4oNVz1hhzIuppTCOQdrJSjA=",
"access_token" : "00D50000000IZ3Z!AQ0AQNag4tr.S15f0LoborG12HIls6eEzIxLafInLZIf6RbFiwV2Pjq6_QHB4J64a6vSMS705Y_sIVE_lq_xnLIXBXgOKPEo"
}

For other cheatsheets: http://developer.salesforce.com/cheatsheets

10132014