Postman and the Salesforce REST API

The Salesforce API is a great way to access Salesforce data and can be used with tools like SoqlXplore or the Salesforce Workbench. The API uses OAuth and a Bearer Authentication, so some steps are required to make that work in Postman

Prepare Salesforce

You will need a connected APP. I usually create one that is pre-approved for my user profile(s), so I don't need to bother with the approval steps in Postman. However you could opt for self-approval and access the app once to approve its use, before you continue with the command line. Note down the ClientId and ClientSecret values.

Prepare Postman

Postman has great build in support for all sorts of authorization interactively. However my goal here is to fully automate it, so you can run a test suite without manual intervention. First stop is the creation of one environment. You can have multiple environments to cater to different Salesforce instances.

Important Never ever ever store the environment into version control. It would contain credentials -> bad bad idea!

My environment variables look like this:

{
 "CLIENT_ID" : "the ClientId from Salesforce",
 "CLIENT_SECRET" : "The ClientSecret from Salesforce",
    "USER_ID" : "some@email.com",
    "PASSWORD" : "DontTell",
    "LOGIN_URL" : "https://login.salesforce.com/"
}

Providing the Login URL allows to reuse postman collections between Sandboxes, Developer Orgs or Production Orgs without the need to actually edit the postman entries. Next on the menu: getting a token

Getting a token

Your Postman URL will look like this: {{LOGIN_URL}}/services/oauth2/token. Depending on the environment you will use production or Sandbox. The request ist an unauthenticated POST with a single header of Content-Type:application/x-www-form-urlencoded The body you post looks like this:

grant_type:password
client_id:{{CLIENT_ID}}
client_secret:{{CLIENT_SECRET}}
password:{{PASSWORD}}
username:{{USER_ID}}

PostMan replaces anything inside {{ .... }} with values from your environment. This approach allows you to share your Postman collections without disclosing what should be private. A successful response will look like this:

{
    "access_token": "some long string that you need in your authorization header",
    "instance_url": "https://yourdomain.my.salesforce.com",
    "id": "https://login.salesforce.com/id/somestring/anotherstring",
    "token_type": "Bearer",
    "issued_at": "1530761889707",
    "signature": "theThirdStringCheckSum"
}

All future call need go to the instance URL with the access token as bearer authorization. To make that easy we use PostMan's test script to capture that values into the environment:

pm.test("Status code is 200", function () {
    pm.response.to.have.status(200);
});

var jsonData = pm.response.json();

pm.test("Has a bearer token", function () {
    pm.expect(jsonData.token_type).to.eql("Bearer");
});

// Save the bearer
pm.environment.set("Bearer", jsonData.access_token);
pm.environment.set("Instance", jsonData.instance_url);

Getting the API version

Our next stop is figuring out the current API version (43.0 at the point of writing). To do this we send a GET request to
{{Instance}}/services/data with a header of Authorization:Bearer {{Bearer}}. This call will return an JSON array with available API versions from 20.0 - 43.0 (at time of writing). Again we use the testing capability to capture the latest version:

pm.test("Response time is less than 200ms", function () {
    pm.expect(pm.response.responseTime).to.be.below(200);
});

pm.test("Status code is 200", function () {
    pm.response.to.have.status(200);
});

var jsonData = pm.response.json();
var maxElements = jsonData.length - 1;
pm.environment.set("service_url", jsonData[maxElements].url);

Now we are ready to call more of the rest API. For example to get the list of all API endpoints you would send a GET request to {{Instance}}{{service_url}} with the familiar header of Authorization:Bearer {{Bearer}}.

Now you have all components in place to create more API calls and tests

As usual YMMV