Use REST API
Learning Objectives
- Log in to Workbench and navigate to REST Explorer.
- Use the describe resource.
- Create an account using REST API.
- Execute a query using REST API.
REST Resources and Methods
A REST resource is an abstraction of a piece of information or an action, such as a single data record, a collection of records, or a query. Each resource in REST API is identified by a named Uniform Resource Identifier (URI) and is accessed using standard HTTP methods (HEAD, GET, POST, PATCH, DELETE). REST API is based on the usage of resources, their URIs, and the links between them.
- Retrieve summary information about the API versions available to you.
- Obtain detailed information about a Salesforce object, such as Account, User, or a custom object.
- Perform a query or search.
- Update or delete records.
A REST request consists of four components: a resource URI, an HTTP method, request headers, and a request body. Request headers specify metadata for the request. The request body specifies data for the request, when necessary. If there’s no data to specify, the body is omitted from the request.
Describe the Account Object
- Log in to your Trailhead Playground and navigate to Workbench.
- For Environment, select Production.
- For API Version, select the highest available number.
- Make sure that you select I agree to the terms of service.
- Click Login with Salesforce.
You’ve arrived at the Workbench home page. For this module, we use only one of Workbench’s many tools, the REST Explorer.
In the top menu, select utilities | REST Explorer .

You can make REST API calls from the REST explorer just like you would from any other HTTP interface. The text in the text box represents a resource URI. For convenience, the top-level domain is omitted from the displayed URI. For example, the full URI of the resource that’s prepopulated in the URI text box is https://foo.my.salesforce.com/services/data/v36.0 .
The radio buttons above the URI represent the standard HTTP methods. To make an API call, enter the resource URI, select the appropriate method, add headers as needed, and click Execute.
Let’s try out the SObject Describe resource. This resource, when combined with the GET method, returns metadata about an object and its fields.
We’ll try describing the Account object. Replace the existing text in the URI text box with /services/data/vXX.0/sobjects/account/describe, where XX maps to the API version you’re using.

- /services/data—Specifies that we’re making a REST API request
- /v36.0—API version number
- /sobjects—Specifies that we’re accessing a resource under the sObject grouping
- /account—sObject being actioned; in this case, account
- /describe—Action; in this case, a describe request
Now make sure that the GET method is selected, and click Execute.

Good work, captain. The Account metadata appears on the screen. And Workbench has nicely formatted the response. To see the raw JSON response, click Show Raw Response.

The Account metadata is displayed in JSON below some HTTP response headers. Because REST API supports both JSON and XML, let’s change the request header to specify an XML response. Next to the HTTP methods, click Headers. For the Accept header value, replace application/json with application/xml. Your request headers look like this.

Click Execute. The raw XML response is returned. Hurrah!
Create an Account
Click Headers. Change Accept: application/xml back to Accept: application/json. Your request looks like this.

{ "Name" : "NewAccount1", "ShippingCity" : "San Francisco" }
Click Execute. You see a response such as the following.

If success: true, the account was created with the returned ID. Expand the errors folder to check for errors.
{ "ShippingCity" : "San Francisco" }
Click Execute.
Uh, oh. Did you get a REQUIRED_FIELD_MISSING response? Expand the REQUIRED_FIELD_MISSING folder, and then expand the fields folder. Your expanded response looks like this.

{ "Name" : "NewAccount2", "ShippingCity" : "New York" }
Click Execute. Success!
Execute a Query
Replace the text in the URI text box with the following text: /services/data/v XX.0/query/?q=SELECT+Name+From+Account+WHERE+ShippingCity='San+Francisco', where XX maps to the API version you’re using.
We replaced spaces with the + character in the query string to properly encode the URI. You can read about HTML URL encoding from the link in the Resources section. Make sure that the GET method is selected, and click Execute.
Expand the records folder. Do you see a folder with the name of the first account we created, NewAccount1? Great. Click it. Now click the attributes folder. Next to url is the resource URI of the account that was returned. Your response looks something like this.

When you write an integration, you can grab this URI from the response to access more details about that account.
Node.js and Ruby Samples
Node.js Sample Using Nforce
var nforce = require('nforce'); // create the connection with the Salesforce connected app var org = nforce.createConnection({ clientId: process.env.CLIENT_ID, clientSecret: process.env.CLIENT_SECRET, redirectUri: process.env.CALLBACK_URL, mode: 'single' }); // authenticate and return OAuth token org.authenticate({ username: process.env.USERNAME, password: process.env.PASSWORD+process.env.SECURITY_TOKEN }, function(err, resp){ if (!err) { console.log('Successfully logged in! Cached Token: ' + org.oauth.access_token); // execute the query org.query({ query: 'select id, name from account limit 5' }, function(err, resp){ if(!err && resp.records) { // output the account names for (i=0; i<resp.records.length;i++) { console.log(resp.records[i].get('name')); } } }); } if (err) console.log(err); });
Ruby Sample Using Restforce
require 'restforce' # create the connection with the Salesforce connected app client = Restforce.new :username => ENV['USERNAME'], :password => ENV['PASSWORD'], :security_token => ENV['SECURITY_TOKEN'], :client_id => ENV['CLIENT_ID'], :client_secret => ENV['CLIENT_SECRET'] # execute the query accounts = client.query("select id, name from account limit 5") # output the account names accounts.each do |account| p account.Name end