Accessing Object Knowledge with Salesforce Platform APIs

·

In case you are new to Salesforce APIs and need to perceive which APIs can be found to entry objects in your Salesforce org, then this weblog submit is for you. The Salesforce Platform supplies APIs that allow you to create, learn, replace, and delete information (generally known as CRUD operations) in your org. We’ll spotlight and examine these APIs that will help you perceive the API panorama out there, and supply hyperlinks to supporting documentation and different weblog posts with extra element.

Salesforce supplies a big and complete assortment of APIs that enable exterior purposes to entry information and capabilities within the Salesforce Clouds. To see the complete checklist of APIs, most of that are past the scope of this submit, check with the API Developer documentation. Moreover, you too can check with help documentation for steering on selecting Salesforce APIs, a few of that are past the main focus of this submit.

APIs for accessing object information in a Salesforce org

The Salesforce Platform supplies a number of APIs to entry object information and carry out CRUD operations on information in your org. Which API it’s best to use relies upon upon the kind of integration you’re implementing, and the way a lot information you might want to entry.

In case you are implementing a UI integration, the place a customized UI must entry information, then use both the UI API or the GraphQL API. Each of those APIs help you work with each metadata and information. Observe that this weblog submit will not be centered on UI integration and doesn’t talk about this state of affairs.

In case you are implementing a non-UI integration, the place an exterior utility must entry information, then the quantity of knowledge that your integration must work with will affect the API it’s best to use.

• Want CRUD entry to particular person information → REST sObject Rows API
• Want CRUD entry to 10s by means of 1000s of information → REST Composite API
• Must retrieve 1-1000s of information → Question API
• Want CRUD entry to massive quantities of knowledge, usually greater than 2,000 information → Bulk API 2.0 or Bulk API

The desk under summarizes and compares the primary capabilities of those APIs that will help you resolve which API is finest in your use case.

REST API

REST API supplies API entry, utilizing the RESTful architectural sample, to a broad vary of knowledge and capabilities on the Salesforce Platform as a set of REST assets below the basis https://<my-domain>.my.salesforce.com/companies/.

The highest-level assets out there below https://<my-domain>.my.salesforce.com/companies/ are:

• REST API: .../information/vXX.0/useful resource/model/. When individuals and Salesforce documentation check with the Salesforce REST API, they’re referring to the versioned assets below this URL.
• Bulk API: .../async/. That is the unique Bulk API, generally known as Bulk v1, whereas Bulk API 2.0 is a part of the REST API. Each of those APIs are mentioned under.
• OAuth endpoints: .../oauth2/. These assets allow you to make OAuth authorization requests to Salesforce. These are out of scope for this weblog submit, so check with the linked documentation if you need extra data.

REST API assets

As launched above, except Bulk API and OAuth, all of the REST API assets are versioned below https://<my-domain>.my.salesforce.com/companies/information/vXX.0/useful resource. As of the Spring ’24 launch, which is API model 60.0, the REST API supplies 48 top-level assets.

The REST API Variations useful resource will retrieve a listing of supported API variations with data together with the model, label, and hyperlink to the model’s root.

The REST API Sources by Model useful resource will retrieve a listing of the out there assets for the desired API model, together with the useful resource title and root.

REST API assets to entry information

As this weblog submit is concentrated on accessing information in your Salesforce org, it’ll give attention to the REST API assets below https://<my-domain>.my.salesforce.com/companies/information/vXX.0/ that present entry to things and information:

• sObject useful resource: .../sobjects/. Performs a variety of operations on particular person information of normal and customized objects.
• Question useful resource: .../question/. Executes a SOQL question to retrieve information.
• Composite assets: .../composite/. Set of assets that may execute a number of operations in a single REST API name.
• Bulk API 2.0 useful resource: .../jobs/. Offers a streamlined workflow for ingesting, extracting, or deleting massive units of knowledge.

Different REST API assets

Whereas we’re discussing REST API, it’s value calling out associated REST API assets below https://<my-domain>.my.salesforce.com/companies/information that present entry to metadata, information, and content material on the Salesforce Platform, however which can be past the scope of this weblog submit:

• Join API: For entry to B2B Commerce, CMS-managed content material, Expertise Cloud websites, recordsdata, notifications, matters, Chatter feeds, customers, teams, and extra
• Search API: For executing SOSL statements
• Limits API: Returns details about the bounds in your org, together with the utmost allocation and remaining allocation based mostly on utilization
• UI API: For constructing Salesforce UIs for native cellular apps and customized internet apps utilizing the identical API that Salesforce makes use of to construct Lightning Expertise and Salesforce for Android, iOS and cellular internet

REST API sObject assets

The set of REST API sObjects help you carry out a variety of operations on normal and customized objects, for instance:

• Get CRUD entry to particular person information
• Traverse object relationships to entry information of associated objects
• Get metadata describing objects
• Get web page layouts and descriptions
• Get an object’s actions

The important thing attribute of sObject assets is that they function on a single object, or on a person file of a single object. For a full checklist of the sObject assets, see the REST API Reference.

As this weblog submit is concentrated on performing CRUD operations on object information, we’re going to spotlight the sObject assets that help you entry particular person object information and traverse object relationships.

Accessing particular person information

sObject assets help you create, retrieve, replace, or delete particular person information for traditional and customized objects.

The sObject Fundamental Data useful resource permits you to create a file in a specified object and returns the file ID. For instance, the next REST API request will create an Account file with the ID of the newly created file returned within the response

The sObject Rows useful resource permits you to retrieve, replace, or delete particular person information in a specified object utilizing the file ID. For instance, the next REST API request will retrieve the Identify, Description, Trade and Web site fields from the Account file with an ID of 0018W00002A4IAPQA3.

Traversing relationships

Utilizing the sObjects Relationship useful resource, you’ll be able to traverse an object’s relationships to retrieve, replace, or delete a associated file. For instance, the next REST API request will retrieve, for the Contact file with an ID of 0038W000020wJDXQA2, the mum or dad Account file’s Identify area.

REST API Question useful resource

The Question useful resource permits you to execute a SOQL question to retrieve information out of your Salesforce org.

As an instance this, the next request executes a quite simple SOQL question to retrieve the Identify and Description fields from an Account file, the place the Account file’s Identify area is ACME Corp.

Observe:the above question and different queries on this weblog submit are usually not URL encoded for readability. When making these Question useful resource calls, it’s best to URL encode your queries.

Relationship queries

The Question useful resource permits you to execute SOQL relationship queries that traverse parent-to-child and child-to-parent relationships between objects to filter and return outcomes. The request under executes a SOQL parent-to-child relationship question to retrieve the Account Identify and Description fields, and the FirstName and LastName fields from all associated Contact information, which may very well be a number of, the place the Account Identify is ACME Corp. The Question useful resource helps nested SOQL parent-to-child relationship queries as much as 5 ranges deep — see the weblog submit Question Extra Knowledge with Nested SOQL Queries for extra particulars.

The Question useful resource also can execute relationship queries that traverse object relationships within the different route. The following request executes a SOQL parent-to-child relationship question to retrieve the FirstName and LastName fields, and the mum or dad Account file’s Identify and Description fields, from Contact information the place the mum or dad Account file’s Identify area is ACME Corp.

Getting question outcomes

A name to the Question useful resource can return as much as 2,000 information at a time. If the consequence consists of greater than 2,000 information, the response accommodates the primary set of information and a Question Locator to a server-side cursor with the remaining information. Use the Question Extra Outcomes useful resource with the Question Locator to retrieve the following batch of information, and repeat this course of till all of the question outcomes have been retrieved. The one restrict is that the cursor and related question outcomes can be found for not than two days; there aren’t any limits on the variety of open cursors a consumer might have. The weblog submit Processing Massive Quantities of Knowledge with APIs (Half 1 of two) discusses how one can use the Question Locator to return greater than 2,000 information.

In the event you want your question to additionally embrace information which were deleted due to a merge or delete, use the QueryAll useful resource, together with the corresponding QueryAll Extra Outcomes and the Question Locator, to retrieve subsequent batches of outcomes. Remember that solely tender deleted information which can be within the recycle bin are returned; deleted information which were purged from the recycle bin can’t be queried.

REST API Composite assets

The Composite assets are a set of REST API assets that may execute a number of operations in a single REST API name. These are assets which can be constructed by combining current REST API assets, so {that a} single request can carry out a number of operations.

Orchestration utilizing Composite assets permits for developer-controlled enterprise logic and performance. Responses from one methodology may be directed as inputs into one other methodology. A number of assets can be utilized in a single name to enhance efficiency.

Composite assets are additionally key for designing environment friendly API use in cellular growth to cut back client-server spherical journeys.

Which Composite useful resource ought to I exploit?

The Composite assets consist of 5 totally different REST API assets that present totally different capabilities, all with the commonality that they mix a number of operations referred to as subrequests right into a single API name. The desk under summarizes and compares the primary traits of every that will help you resolve which useful resource is finest in your use case.

The weblog submit Processing Massive Quantities of Knowledge with APIs (Half 2 of two) discusses writing information utilizing the Composite, Composite Batch, and Composite Graph assets in additional element.

Composite useful resource

The Composite useful resource permits you to execute a sequence of REST API sub-requests in a single name from the consumer, utilizing the output of 1 sub-request because the enter to a subsequent sub-request. The HTTP standing codes and response our bodies of all of the sub-requests are returned in a single response to the consumer.

Within the instance under, the primary sub-request creates an Account file and references the output as refAccount. The second sub-request creates a Contact file parented below the newly created Account file by referencing refAccount.

Composite Graph useful resource

The Composite Graph useful resource supplies a extra highly effective technique to orchestrate a number of REST API requests in a single name. This useful resource permits you to make a single request that consists of a number of unbiased graphs, with every graph consisting of a number of REST API sub-requests.

On this instance, we have to carry out the next as a single name:

• Create Account 1 file
• Create Account 2 file, as a baby of Account 1 file
  • Create Contact 1 file, as a baby of Account 2 file
  • Create Contact 2 file, who studies to Contact 1 file
  • Create Contact 3 file, who studies to Contact 2 file
• Create a Marketing campaign file
• Create an Alternative file, linked to the Account 1 file and the Marketing campaign file
• Create a Lead file
• Create a CampaignMember file, linked to the Lead file and the Marketing campaign file

We will symbolize these information as a graph.

The request under reveals how the Composite Graph useful resource can be utilized to create the above graph of information.

sObject Tree resource

The sObject Tree resource allows you to create a tree of nested, parent-child records with a single root record. The request can contain the following:

• Up to a total of 200 records across all trees
• Records of up to five different sObjects types
• sObject trees up to five levels deep

As an sObject Tree request can contain a single record, you can use this resource to create up to 200 unrelated records of the same type.

The example below creates these records:

• Account record ref1
  • Contact record ref2, related to parent Account record ref1
  • Contact record ref2, related to parent Account record ref1
• Account record ref4

sObject Collections useful resource

The sObject Collections useful resource permits you to execute CRUD actions on a number of, unbiased information in a single request. The request, response, and habits rely upon the motion being carried out as proven within the desk under.

The sObject Collections useful resource helps the identical headers and the identical limits because the SOAP API, and permits for a migration from SOAP API to REST API.

The instance under reveals the Create motion.

The instance under reveals the Retrieve motion.

SOAP API

SOAP API is an older API that’s well-suited for older system integrations, integrations that want well-defined interfaces utilizing WSDL, and integrations which can be performing operations on 200 or fewer information. A number of the key traits of SOAP API are:

• Offers two flavors of WSDL: the Enterprise WSDL and the Associate WSDL:
  • The Enterprise WSDL describes SOAP operations for a single org and contains object customizations
  • The Associate WSDL describes SOAP operations which can be agnostic to org-specific customizations and is best fitted to companions constructing purposes that work throughout a number of orgs (see docs for extra particulars)
• Helps XML information solely
• Authenticate with the SOAP login name
• Synchronous
• Permits operations on as much as 200 information at a time

Whereas totally supported, SOAP API is not being enhanced. We advocate that you just use the REST API for all new developments.

Bulk APIs

The Bulk APIs are optimized for ingesting, extracting, or deleting massive units of knowledge. They’re finest suited when you might want to course of greater than 2,000 information.

The Bulk APIs function asynchronously, permitting Salesforce to course of the request within the background. On account of this asynchronous nature, there isn’t a SLA on how shortly the Bulk APIs will course of requests.

There are two Bulk APIs out there:

• Bulk API 2.0 is the newer API. It supplies a streamlined and easier-to-use workflow, and is the main focus for enhancements. Bulk API 2.0 is a part of REST API, and the URL root is https://<my-domain>.my.salesforce.com/companies/information/vXX.0/jobs.
• The unique Bulk API. Whereas totally supported, Bulk API is not being enhanced. We advocate that you just use Bulk API 2.0 the place attainable.

Evaluating Bulk API 2.0 and Bulk API

The desk under summarizes the variations between Bulk API 2.0 and Bulk API. You will discover extra particulars on the variations within the documentation.

The weblog posts Processing Massive Quantities of Knowledge with APIs (Half 1 of two) and Processing Massive Quantities of Knowledge with APIs (Half 2 of two) describe studying and writing massive quantities of knowledge utilizing Bulk API 2.0 and Bulk API.

Apex REST & SOAP

Apex is the native programming language for the Salesforce Platform. You possibly can create Apex lessons and expose these lessons as REST API assets utilizing Apex REST and as SOAP Net Companies utilizing Apex SOAP. This supplies you with a customized method to exposing information in your Salesforce org to exterior purposes. For instance, your Apex lessons may apply your particular enterprise guidelines when studying and writing information. To study extra, watch this codeLive session exhibiting how one can write Apex REST companies.

Salesforce Integration consumer license

A remaining consideration for utilizing these Salesforce Platform APIs is which consumer to make use of to hook up with your org. We advocate that every exterior utility that connects to Salesforce to invoke APIs does so utilizing its personal devoted consumer. This ensures that every utility solely has entry to the info and operations that it wants and nothing extra whereas offering distinct auditability and traceability of requests from every utility.

The Salesforce Integration consumer license supplies an economical method to integrating every of your purposes to Salesforce utilizing a devoted consumer. Calling REST APIs, together with Bulk API 2.0 and Apex REST, utilizing the Salesforce Integration consumer license with the OAuth Shopper Credentials flows is mentioned on this weblog submit.

Postman assortment

Now that we’ve reviewed the APIs wanted to entry information in your Salesforce org, it’s time so that you can attempt them out. Salesforce supplies a Postman assortment with 200+ request templates for tens of Salesforce APIs. This assortment permits you to simply authenticate and check out requests to the APIs, so you’ll be able to expertise how every API works. See the weblog submit Discover the Salesforce APIs with the Upgraded Postman Assortment for extra data. As well as, see our codeLive session on exploring the Salesforce Platform APIs with Postman.

Conclusion

As highlighted above, the Salesforce Platform supplies a breadth of APIs with a broad vary of capabilities for accessing information in your org. This weblog submit has supplied an introductory overview of these APIs that will help you perceive what is accessible to you and that will help you resolve which APIs are finest suited in your use case. There are hyperlinks to additional data inside the submit and within the assets under. Lastly, see our webinar for additional insights into API and integrating with the Salesforce Platform.

Sources

Concerning the writer

Jeremy Westerman is a Director of Product Administration at Salesforce, the place he’s accountable for Salesforce APIs to entry information on the core Salesforce Platform. Observe him on LinkedIn and the Trailblazer Community.

Accessing, APIs, Data, Object, Platform, Salesforce