25 May 2018
A Guide To Salesforce REST API
Vaibhav Singh
#Technology | 5 Min Read
Salesforce provides a REST API for interacting with its platform. It is the most common way to integrate with the third party services/applications. Its advantages include ease of integration and development, and it’s an excellent choice of technology for use with mobile applications and Web 2.0 projects.
The Salesforce REST API is best suited for browser or mobile apps which don’t need access to high amounts of records. In case you want to access high amounts of records you should probably explore Salesforce BULK API. Salesforce REST API supports JSON and XML.
The Salesforce REST API is best suited for browser or mobile apps which don’t need access to high amounts of records. In case you want to access high amounts of records you should probably explore Salesforce BULK API. Salesforce REST API supports JSON and XML.
Step 1: Setting up OAuth 2.0
Before we can access any Salesforce data we will have to authenticate ourselves using OAuth 2.0. But we will have to first enable OAuth 2.0 on our Salesforce account.
- Create a connected app in Salesforce
- Enter Apps in the Quick Find box, select Apps (under Build | Create), then click the name of the connected app.
- Enable OAuth settings and specify your callback URL and OAuth scopes.
- On clicking SAVE, a consumer key and consumer secret are generated.
- Web server flow, where the server can securely protect the consumer secret.
- User-agent flow, used by applications that cannot securely store the consumer secret.
- Username password flow, where the application has direct access to user credentials.
Step 2: Logging In
To access data on Salesforce we need to authorize ourselves using an access token. Using the OAuth flow we will be generating the access token.
The access token can be obtained by making a POST request to the appropriate endpoint such as https://login.salesforce.com/services/oauth2/token or https://test.salesforce.com/services/oauth2/token. The required parameters are:
a. grant_type: The value should be ‘password’
b. client_id: The Consumer Key from the connected app definition.
c. client_secret: The Consumer Secret from the connected app definition.
d. username: yourusername@domain.com end-user’s username.
e. password: yourpasswordXXXXXXXXXX, we will need to generate a security token from our Salesforce account. For example, if a user’s password is yourpassword, and their security token is XXXXXXXXXX, then the value provided for this parameter must be yourpasswordXXXXXXXXXX.
These parameters are passed as x-www-form-urlencoded. The request body will look something like this :
The access token can be obtained by making a POST request to the appropriate endpoint such as https://login.salesforce.com/services/oauth2/token or https://test.salesforce.com/services/oauth2/token. The required parameters are:
a. grant_type: The value should be ‘password’
b. client_id: The Consumer Key from the connected app definition.
c. client_secret: The Consumer Secret from the connected app definition.
d. username: yourusername@domain.com end-user’s username.
e. password: yourpasswordXXXXXXXXXX, we will need to generate a security token from our Salesforce account. For example, if a user’s password is yourpassword, and their security token is XXXXXXXXXX, then the value provided for this parameter must be yourpasswordXXXXXXXXXX.
These parameters are passed as x-www-form-urlencoded. The request body will look something like this :
grant_type=password&client_id=3MVG9lKcPoNINVBIPJjdw1J9LLM82Hn
FVVX19KY1uA5mu0QqEWhqKpoW3svG3XHrXDiCQjK1mdgAvhCscA9GE&client_secret=
1955279925675241571&username=testuser%40salesforce.com&password=yourpassword123456XXXXXXX
Salesforce will verify the user credentials and if authenticated returns the following response with the access token.
{"id":"salesforce_id",
"issued_at":"1278448832702",
"instance_url":"https://***yourInstance***.salesforce.com/",
"signature":"0CmxinZirTD+zMpvIWYGb/bdJh6XfOH6EQ=",
"access_token": "00Dx0000000BV7z"}
We can use this access token to access the data on Salesforce.
Step 3: Accessing Data
Every HTTP method is used to indicate a specific action in Salesforce.
1. Getting Salesforce version:
URL: https://yourInstance.salesforce.com/services/data/
method type: GET
2. Getting List of Resources:
URL: https://yourInstance.salesforce.com/services/data/{version}/
method type: GET
This method returns the list of resources available on the Salesforce version provided in the URL, example: v20.0
3. Getting List of Objects:
URL:https://yourInstance.salesforce.com/services/data/v20.0/{resource_name}
method type: GET
This provides us the available objects in the resource, (subjects) passed in the URL.
4. Getting Object Metadata:
URL:https://yourInstance.salesforce.com/services/data/v20.0/sobjects/{Object Label}
method type: GET
This provides us the metadata for the Object, like Account’s object here.
5. Getting Record Data:
URL:https://yourInstance.salesforce.com/services/data/v20.0/sobjects/Accounts/{Object ID}
method type: GET
This provides us the data of the objects based on the Id which we pass in the request.
6. SOQL for Custom retrieval:
Salesforce provides a an option to execute SOQL queries which are very similar to SQL queries to retrieve data.
Example of SOQL:
URL:https://yourInstance.salesforce.com/services/data/v20.0/query?q=Select+name+from+Account
method type: GET
- HEAD is used to retrieve object/record metadata.
- GET is used to retrieve information about record/object.
- POST is used to create a new object.
- PATCH is used to update a record.
- DELETE is used to delete a record.
1. Getting Salesforce version:
URL: https://yourInstance.salesforce.com/services/data/
method type: GET
2. Getting List of Resources:
URL: https://yourInstance.salesforce.com/services/data/{version}/
method type: GET
This method returns the list of resources available on the Salesforce version provided in the URL, example: v20.0
3. Getting List of Objects:
URL:https://yourInstance.salesforce.com/services/data/v20.0/{resource_name}
method type: GET
This provides us the available objects in the resource, (subjects) passed in the URL.
4. Getting Object Metadata:
URL:https://yourInstance.salesforce.com/services/data/v20.0/sobjects/{Object Label}
method type: GET
This provides us the metadata for the Object, like Account’s object here.
5. Getting Record Data:
URL:https://yourInstance.salesforce.com/services/data/v20.0/sobjects/Accounts/{Object ID}
method type: GET
This provides us the data of the objects based on the Id which we pass in the request.
6. SOQL for Custom retrieval:
Salesforce provides a an option to execute SOQL queries which are very similar to SQL queries to retrieve data.
Example of SOQL:
URL:https://yourInstance.salesforce.com/services/data/v20.0/query?q=Select+name+from+Account
method type: GET
Summary
Salesforce’s REST APIs are pretty straightforward, easy to integrate and works with simple HTTP requests, but there are many open source packages which provide a wrapper around these HTTP requests and provide a simple interface for the developers. A few of them are:
* Python: simple-salesforce
* Node: node-salesforce
* Ruby: restforce In case you are looking for Salesforce BULK APIs, check out the documentation here.
* Python: simple-salesforce
* Node: node-salesforce
* Ruby: restforce In case you are looking for Salesforce BULK APIs, check out the documentation here.