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:
| Request | Gives |
|---|---|
GET /services/data/ | the API versions the org offers |
GET …/sobjects | every object, with what you may do with it |
GET …/sobjects/Account/describe | an 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/Account | create a record: 201 and { "id": "001…", "success": true } |
PATCH …/sobjects/Account/001… | change fields: 204, no body |
DELETE …/sobjects/Account/001… | delete: 204 |
GET …/limits | how 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.Namereaches 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 likeLAST_N_DAYS:30work too. SELECT COUNT() FROM Contactgives only the number, intotalSize.- 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" } ]
| Status | errorCode | Usually means |
|---|---|---|
400 | MALFORMED_QUERY, INVALID_FIELD | a mistake in the SOQL, or a field the user can't see |
400 | REQUIRED_FIELD_MISSING, FIELD_CUSTOM_VALIDATION_EXCEPTION | a create or change broke a rule set up in the org |
401 | INVALID_SESSION_ID | the token expired or is wrong: sign in again |
403 | REQUEST_LIMIT_EXCEEDED | the org has used up an API limit |
404 | NOT_FOUND | wrong 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. ThecompositeAPI 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 gets401. - Your queries return the fields your integration reads, with the types it expects. Check
describefor the fields that matter. - Paging: with more records than one page, the integration follows
nextRecordsUrluntildoneistrue. - Rules in the org: a create that misses a required field gets the right
400and 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: Bearerto theinstance_url. Expect401 INVALID_SESSION_IDwhen 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
nextRecordsUrluntildone. - 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.