Getting Started with the Salesforce Lightning Platform's REST API

Salesforce offers several APIs with different tools and functionality in mind. The API best suited for interacting with Salesforce records (i.e. CRUD actions), is the Lightning Platform REST API.

If you're unsure which Salesforce API you want to use, there's a good chance this is the one.

In general, the API adheres to many RESTful practices, including use of HTTP verbs (GET, POST, PATCH, PUT and DELETE.) to denote the action, well formed URLs to specify object and record context and the API version, and use of JSON when sending and receiving data.

In my career I have worked with many APIs on many platforms with many levels of developer friendliness. If you're reading this, you'll probably appreciate that the Salesforce system is very developer friendly -- lots of documentation, highly reliable and for the most part everything works as you would expect it to in terms of adhering to RESTful practices.

API Versioning

The Salesforce development cycle provides for three releases every year, and with every update to the platform the API can be updated as well. Every REST API call will specify the version for which the call was written, and legacy API versions are preserved (perhaps indefinitely). Writing an integration for the current release is sufficient and will likely not need to be updated for quite some time.

Connected App

Prior to connecting your tooling with Salesforce, you'll need to create (or re-use) a Connected App.

Authentication

Flow Option: Username-Password

Salesforce offers different authentication strategies for different scenarios. For non-interactive integrations, the best choice is the Username-Password flow, in which the username, password, client id and client secret are sent to the login endpoint (prefixed with either https://login.salesforce.com or https://test.salesforce.com, depending on if the targeted system is a Production system or Sandbox). The API responds to a successful request with

• an Access Code, which is used in place of the credentials in future API calls
• an Instance URL, e.g. https://na35.salesforce.com/, to which you will send your future API calls (i.e. send calls here instead of https://login.salesforce.com or https://test.salesforce.com)

Note that when sending the password through this flow, it should be joined with the security token, e.g.

PASSWORD='SomePassword';
SECURITY_TOKEN='SomeToken';

# build the password + token string
PASSWORD_AND_SECURITY_TOKEN="$PASSWORD$SECURITY_TOKEN"

echo $PASSWORD_AND_SECURITY_TOKEN
# will show: SomePasswordSomeToken

Example Code

The below authentication example is in Bash and leverages jq to help us interpret and manipulate the JSON API responses.

#!/usr/bin/env bash

BASE_URL='';
CLIENT_ID='';
CLIENT_SECRET='';
USERNAME='';
PASSWORD='';
SECURITY_TOKEN='';

# build the password + token string
PASSWORD_AND_SECURITY_TOKEN="$PASSWORD$SECURITY_TOKEN"

# authentication
string_response=$(curl --silent --request POST \
  "$BASE_URL/services/oauth2/token" \
  --data "grant_type=password&client_id=$CLIENT_ID&client_secret=$CLIENT_SECRET&username=$USERNAME&password=$PASSWORD_AND_SECURITY_TOKEN")

# check for an authentication error
errorCode=$(echo ${string_response} | jq '.errorCode')
if [ "$errorCode" != "null" ]; then
  echo "Authentication Error"
  echo $errorCode
  exit 1
fi

# identify the access_token and instance_url using jq, trim the leading and
# trailing " characters from the strings
# https://stedolan.github.io/jq/
access_token=$(echo ${string_response} | jq '.access_token' | cut -c 2- | rev | cut -c 2- | rev)
instance_url=$(echo ${string_response} | jq '.instance_url' | cut -c 2- | rev | cut -c 2- | rev)

# access token will contain a ! which will needs to be escaped since it has
# special meaning within Bash
access_token="${access_token/!/\!}"

Basic Query

After the initial authentication API call, all API calls will be directed to the retrieved Instance URL and include an authorization header as shown below.

# basic Account object search query. Note that query is a GET, so the URL we
# build will start with the Instance URL we got from the authentication call.
QUERY_URL="$instance_url/services/data/v43.0/query/?q=select+Id,Name+from+Account+LIMIT+2"

string_response=$(curl --silent --request GET \
  "$QUERY_URL" \
  --header "Authorization: Bearer $access_token")

# check for an API error
errorCode=$(echo ${string_response} | jq '.errorCode')
if [ "$errorCode" != "null" ]; then
  echo "API Error"
  echo $errorCode
  exit 1
fi

totalSize=$(echo ${string_response} | jq '.totalSize')
echo "there were $totalSize results:"
echo ${string_response} | jq '.records[].Name'

More Examples Code in API Wrappers

I've written a wrapper for PHP to assist in working with the Salesforce API:

• https://github.com/matthewpoer/php-salesforce-wrapper

Even more on Trail Head

If you aren't already aware of and a fan of Salesforce's Trailhead, may I humbly demand you check it out ASAP. Trailhead is Salesforce's own learning management system. That is, it's more than documentation: it's a series of learning paths to help you learn what you need to learn about Salesforce's product offerings, complete from End Users, Administrators to Developer focus.

Since you're reading this, a great starting place would probably be the Use REST API module.