Integrating with Salesforce APIs: Tips and Tricks

Salesforce, the original SaaS app, has several APIs for developers to use with integrations. Developers who have been working with Salesforce for a long time are often most familiar with the SOAP API, but Salesforce now includes REST, GraphQL, and gRPC APIs.

We are visiting again with Taylor Reece, a Developer Advocate at Prismatic, to discuss some tips and tricks for developers who need to work with Salesforce APIs for integrations.

Bru: Taylor, Salesforce has been around a while, and its flexibility has undoubtedly been a factor in its longevity. How does that flexibility work on the data end of things?

Taylor: Sure. You can customize Salesforce data structures like crazy. The system comes with a number of standard record types, such as Lead, Contact, and Account.

But, few Salesforce customers stick with those standard record types or even the standard fields.

Instead, they'll add any number of new fields to existing record types and even add completely new record types to the schema. They may even change all the labels on standard fields.

As you might imagine, just about every Salesforce customer ends up with a custom schema. It makes things really sticky since a customer can conceivably store just about anything in Salesforce, but it creates a fair amount of work for the devs who need to integrate with Salesforce.

Bru: Custom objects and fields in systems are often treated as second-class items in terms of accessibility. How does Salesforce handle them?

Taylor: In general, Salesforce makes custom record types (objects) and fields automatically accessible via its APIs. So, the data is there and not hidden via some special, convoluted process.

The key to working with the Salesforce data schema is to manage the field mapping. This process goes something like this:

1. Select the name of the object (example: Leads).

2. View all the fields for the object (including custom).

3. Map the field (example: "Lead FirstName__c" to whatever you need).

The simple thing to remember here is that standard objects and fields in Salesforce don't have the double-underscore c suffix, but every custom object and field has that suffix.

Bru: OK. Let's talk a bit about the different Salesforce APIs. What do devs need to know about them?

Taylor: Certainly. Salesforce has a dozen or so APIs. And, if you want to, you can access them natively via SOAP, REST, GraphQL, or gRPC. In many cases, you can use SOQL (Salesforce Object Query Language) to build specific queries against the data.

But that's not usually the most efficient approach to using Salesforce APIs with integrations. Instead, you should use third-party libraries (such as jsforce).

These libraries abstract the Salesforce APIs to the point where you don't need to know exactly which API you'll be hitting with a specific request. Instead, the library brokers that request, sending it to the right API with the right data format.

Bru: Nice. That simplifies something that otherwise appears quite complicated.

Taylor: Yes, it really does. We used jsforce to build Prismatic's Salesforce connector. Without that, it could have easily been an order of magnitude more effort to get everything set up.

On the backend, we primarily connect to Salesforce with jsforce via the GraphQL and REST APIs, but the nice thing is that I don't have to know or care what goes into a given GET or POST since jsforce handles them.

Bru: Let's look at a recurring topic for these API discussions: webhooks. What is special about webhooks for Salesforce APIs?

Taylor: Well, Salesforce definitely has its own way of handling webhooks. The first thing to know is that when something happens in Salesforce, instead of alerting one thing (as is the case with most webhooks), you need two separate things. These are the outbound message and the workflow rule. We'll call them the message and the rule to make things simple.

Now, into the details. The message declares the object and field names (a manifest, if you will) for the data to be sent. For example, you might specify a message with the accounts object with the corresponding ID and annual_revenue fields.

The rule defines (for our example), "When the account object is updated, send the message." The rule doesn't know anything except that the notification event occurred. But, when the rule runs, the message is sent to the webhook endpoint.

So, for Salesforce, you need to remember to set up both pieces (the message and the rule) for every webhook, or your data won't be sent when needed.

Bru: That sounds manageable overall. Is this for all Salesforce webhooks, or is there another approach that devs could use?

Taylor: Right now, this is the primary approach that Salesforce uses for webhooks. However, Salesforce recently implemented an API just for messaging: the Pub/Sub API. We have yet to work with this in any detail, but it seems to follow a pattern similar to what Google implemented for its Cloud Pub/Sub functionality.

For now, we will stick with the tried-and-true approach to webhooks using the outbound message and rule. However, I think we'll likely implement the Pub/Sub functionality for our Salesforce connector in the not-too-distant future – as long as those updates make sense for our customers. We won't, however, be removing our current webhook functionality.

Bru: Excellent. Taylor, thank you for sharing your knowledge of Salesforce APIs.

Schedule a demo to see how Prismatic makes it easier to build integrations connecting your app to Salesforce and then deploy and manage them at scale while providing an in-app integration UX for your customers via the white-label marketplace and embedded designer.