Use REST API

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.

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.

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.

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!

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!

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.

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);
});

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