Salesforce REST API Guide

2024-01-25

1. Getting Started

Salesforce has a large library of APIs, but here we are going to use their REST API. The API access is enabled by default in Enterprise, Performance, Unlimited, and Developer Edition orgs. Professional Edition orgs can add API access as an add-on.

2. Getting Your User Access to Salesforce REST API

To access it, the user must have the API Enabled permission turned on in the user profile they’re assigned. This permission is enabled by default on some profiles, including many profiles available in Developer Edition orgs.

To turn on this setting:

1. Click the Gear icon and click Setup.
2. Search and go to “profiles” in the search bar
3. Click Edit in the Profile you want to enable API access
4. Scroll down to Administrative Permissions and check the API Enabled box and click Save

3. Creating an App

Now that you have grant your user access to the API, the next step is to create a Connected App.

To do so:

1. Open Setup home
2. Go to home -> Apps -> Manage apps -> new connected app
3. In the App Manager, set the Name, API Name and contact Email
4. Enable OAuth Settings, and set the callback URL to sfdc://oauth/restapi/success
5. Select the scope : Access and manage your data (api)
6. Save the connected app and wait few minutes for it to be activated.
7. Save the consumer key and consumer secret

4. Connect to the REST API

Salesforce uses OAuth 2.0 Username-Password Flow. This means that you must get an Access Token, that will be used to access all other available endpoints. To get this token, you have to make a POST request to the following endpoint:

api_base_url + "/services/oauth2/token"

• Where api_base_url is the URL used to access the Salesforce instance through the browser

With the following Body:

{
	  "grant_type": "password",
	  "client_id": {client_id},
	  "client_secret": {client_secret},
	  "username": {username},
	  "password": {password} + {security_token}
}

• Where Username and password are the credentials used to access the Salesforce instance through the browser
• Note that in password, you have to concatenate the Account’s password with the security_token

Salesforce returns the response that contains the access token and instance_url :

{
		"access_token": "{token}",
		"instance_url": "{instance_url}",
		"id": "{ID}",
		"token_type": "Bearer",
		"issued_at": "{date_stamp}",
		"signature": "{signature}"	
}

5. Using the REST API

5.1. Authentication

To call any endpoint, you have to use the access_token we got from the last step. To do so, you have to add to your headers the following line:

"Authorization": "Bearer {access_token}"

5.2. Getting The Schema of an Object

To get information from an object, you can use GET requests. To get the schema of an Salesforce Object, you can use the endpoint:

{instance_url}/services/data/v58.0/sobjects/{Object}/describe

it will return the information of all fields in this object, as its name in the web UI, in the API, its type, etc.

5.3. Getting an instance of an object

To get access to a object, you need to have their id. Once you have it, you can call the following end-point with a GET request to get all of their information:

{instance_url}/services/data/v58.0/sobjects/{Object}/{id}

5.4. Creating an Object instance

To create an object instance, you have to make a POST request, with the data you want filled in as the body of the request. Note that some objects have mandatory fields, that if they are not automatically created, you MUST have in your request body, otherwise it will return an error.

The end-point should be:

{instance_url}/services/data/v58.0/sobjects/{Object}/

The body of the request should look like this:

{
	"{Object_field_name_1}" "{value}",
	"{Object_field_name_2}" "{value}",
	"{Object_field_name_3}" "{value}"
}

If successful, the request will return the id of the newly created object:

{
	"id": "{id}",
	"success": true,
	"errors": []
}

5.5. Updating Object Data

To create an object instance, you have to make a PATCH request, with the data you want updated as the body of the request.

If you try to update a field that does not exists, the request will return an error.

The endpoint to do this is

{instance_url}/services/data/v58.0/sobjects/{Object}/{id}

6. SOQL

6.1. What is SOQL

SOQL is a query language designed for querying data within Salesforce. It's similar to SQL (Structured Query Language) but is specifically made for Salesforce data, the biggest difference being that while SQL works with tables, SOQL works with Objects (like MongoDB).

6.2. Getting Access

We can access and make requests via the REST API, making a GET request to the endpoint

{instance_url}/services/data/v58.0/query/

with the query as a param:

?q={query}

The full URL of the request should look like this:

{instance_url}/services/data/v58.0/query/?q={query}

6.3. SOQL Cheat Sheet

SOQL is very similar to SQL to have a quick start, bellow is a cheat sheet with the main operations

For a more in-depth cheat sheet please see this one by salesforceben.com

6.4. Request Responses

If successful, the request response will be a JSON with the data you queried as the result. For examplie, this query:

SELECT id, Name FROM Account LIMIT 2

Will have a response of

{
	{
		"metadata": {...},
		"id": "{id_1}",
		"name": "{Name_1}"
	},
	{
		"metadata": {...},
		"id": "{id_2}",
		"name": "{Name_2}"
	}
}

6.5. Limitations

SOQL cannot create or update data, as it is meant to be used only for getting it. To update or create new data, you have to use the previously described methods.