Business systems

The Salesforce REST API

How Salesforce's REST API works and how to test it — signing in with OAuth, objects and describe, SOQL queries and their pages, the errors it sends back, API limits, and load testing without using up your org's allowance.

Salesforce keeps a company's customers, deals and support cases, and nearly every other system that needs them reads them through its REST API. If you test an integration with Salesforce (a website form that creates leads, a nightly sync to finance, a portal that shows a customer's cases), this is the API in the middle. Once you know four things, it's easy to read: signing in, objects, SOQL, and limits.

Signing in: OAuth 2.0, then a token on every request

Salesforce never takes a password on API calls. An app is set up in Salesforce first (an External Client App; older orgs have Connected Apps). It gets a consumer key and consumer secret, which are its client ID and secret. Your test signs in with them at the token address:

POST https://your-company.my.salesforce.com/services/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=…&client_secret=…

The answer has two things you need:

{ "access_token": "00D…", "instance_url": "https://your-company.my.salesforce.com", "token_type": "Bearer" }

Every later request sends Authorization: Bearer <access_token> to the instance_url. A token expires after a while (the org's session settings decide when), and then requests fail with 401 and INVALID_SESSION_ID. A good test signs in at the start rather than keeping an old token. Client credentials is the usual grant for server-to-server tests. When a person signs in through a browser, it's the authorization code grant instead. Signing in explains both.

Objects, and asking an object to describe itself

Everything in Salesforce is an object (Account, Contact, Opportunity, Case, and custom objects that end in __c). Under /services/data/v62.0/ (the API version, which changes three times a year) you'll find:

RequestGives
GET /services/data/the API versions the org offers
GET …/sobjectsevery object, with what you may do with it
GET …/sobjects/Account/describean object's fields: name, label, type, length, required, the objects it links to
GET …/sobjects/Account/001…one record, by its 15- or 18-character ID
POST …/sobjects/Accountcreate a record: 201 and { "id": "001…", "success": true }
PATCH …/sobjects/Account/001…change fields: 204, no body
DELETE …/sobjects/Account/001…delete: 204
GET …/limitshow much of each limit the org has used today

Describe is to Salesforce what $metadata is to OData: the API describing itself. Use it in a test to catch a field that was renamed, made required or removed. That kind of change breaks integrations without anyone noticing.

SOQL: reading records

Reading uses SOQL, a query language that looks like SQL. It goes in the q parameter of …/query:

GET …/query?q=SELECT Id, Name, Industry, Owner.Name FROM Account WHERE Industry = 'Banking' ORDER BY Name LIMIT 50
  • Owner.Name reaches through a link to the parent record. A child list goes in brackets: (SELECT LastName FROM Contacts).
  • Text goes in single quotes, and dates and numbers don't: CreatedDate > 2024-01-01T00:00:00Z. Words like LAST_N_DAYS:30 work too.
  • SELECT COUNT() FROM Contact gives only the number, in totalSize.
  • There's no SELECT *. You name the fields you want, and that keeps answers small.

The answer comes in pages

{ "totalSize": 4512, "done": false, "nextRecordsUrl": "/services/data/v62.0/query/01gD…-2000",
  "records": [ { "attributes": { "type": "Account", "url": "…" }, "Id": "001…", "Name": "Acme" } ] }

totalSize is how many records match. records is only this page: up to 2,000 by default. While done is false, GET the instance_url followed by nextRecordsUrl to read the next page. A test that counts records without checking done counts one page, so it passes with a small org and fails with a real one.

When it goes wrong

Errors come as a list, each one with a code you can check:

[ { "message": "No such column 'Nmae' on entity 'Account'.", "errorCode": "INVALID_FIELD" } ]
StatuserrorCodeUsually means
400MALFORMED_QUERY, INVALID_FIELDa mistake in the SOQL, or a field the user can't see
400REQUIRED_FIELD_MISSING, FIELD_CUSTOM_VALIDATION_EXCEPTIONa create or change broke a rule set up in the org
401INVALID_SESSION_IDthe token expired or is wrong: sign in again
403REQUEST_LIMIT_EXCEEDEDthe org has used up an API limit
404NOT_FOUNDwrong ID, object or API version

A field the user's profile can't see behaves exactly like a field that doesn't exist. Test with the same user and permissions your integration runs as, not an admin.

Limits: every request counts

A Salesforce org has a daily allowance of API requests, shared by every integration that uses it. How big it is depends on the edition and the number of licenses. Each answer tells you where you stand, in a header:

Sforce-Limit-Info: api-usage=18250/100000

GET …/limits gives the full picture (DailyApiRequests, with Max and Remaining), and Salesforce also limits how many long requests may run at once. So:

  • Check the header in your tests: a run that suddenly uses far more requests than usual is a bug, even when everything passes.
  • Load-test in a sandbox, never in production, and only with the org owner's agreement. Salesforce asks customers to follow its performance-testing policy, so read it before you start. A performance test of a few minutes can use thousands of requests from an allowance that the company's real integrations need too.
  • Ask for less, fewer times: name only the fields you need, and prefer one query with IN (…) to fifty single-record reads. The composite API can send up to 25 requests as one.

What to test

  • Sign-in: a good token works; a wrong secret gets 400 invalid_client; no token gets 401.
  • Your queries return the fields your integration reads, with the types it expects. Check describe for the fields that matter.
  • Paging: with more records than one page, the integration follows nextRecordsUrl until done is true.
  • Rules in the org: a create that misses a required field gets the right 400 and code, and your integration shows it instead of losing the record.
  • Permissions: the integration user sees what it should, and nothing more.
  • API use: how many requests one run makes, so a change that doubles it is noticed.

Key takeaways

  • Sign in with OAuth 2.0, then send Authorization: Bearer to the instance_url. Expect 401 INVALID_SESSION_ID when the token expires.
  • Describe tells you an object's fields. Test it, so a renamed or removed field is noticed.
  • SOQL reads records a page at a time: follow nextRecordsUrl until done.
  • Every request counts against the org's daily API allowance. Watch Sforce-Limit-Info, and load-test only in a sandbox, with agreement.

In the app: Connect a Salesforce org and browse it · Templates · OAuth 2.0 sign-in

Salesforce is a trademark of Salesforce, Inc. APITestCenter works with its API and isn't endorsed by Salesforce.

Next: NetSuite REST web services and SuiteQL

A question these lessons don’t answer? Write to support@apitestcenter.com — we add lessons for the questions people ask.