Note: This post was written for Salesforce business analysts and administrators, but even if you don't use Salesforce, you can still get a pretty good idea what an "API" is used for by reading it.

Salesforce folks: Have you ever been told that you might need a “REST API” to integrate outside data with Salesforce?

If you’re confused, you’re in good company, because it means different things in different contexts!

Read on for a “30,000-foot view” of all 3 variations on the phrase “REST API” in Salesforce.

3 major concepts, all called “REST APIs”

1: Build Your Own “Endpoint” Inside Salesforce

When people mention “building REST APIs inside of Salesforce,” they mean using the “Apex” language to program a specific Salesforce database (“org”) to accept requests from the outside world to engage in a computer-to-computer data-transferring conversation over the web.

The data can potentially flow both ways (more in a second), but only via the outside world knocking on your Salesforce org’s door and saying, “Hey, I’ve got another communications request!” in the exact manner that you’ve said you want your Salesforce org to be communicated with.

That’s what “writing an API” means – it means using code to define how a computer is willing to have its door knocked on and be talked to.

When you “build a REST API” inside of Salesforce, you’re building a door in your fortress and posting a guard by it who’s cautious about how she interacts with strangers on the other side.

• You might program your Salesforce org to know what to do with data from the outside world, but only when delivered correctly. If your API were in the physical world, it might look something like this:

“If you have something for the fortress, bring it in a series of pink 12x12x12 boxes, only paint the first one with green stripes and the last one with purple polka dots, and put your name and return address on all of them. If we like them, we’ll figure out what to do with the stuff inside the boxes from there. After we’re done, we’ll post a receipt on the door telling you whether we handled them neatly or burned them.”

• Or you might program your Salesforce org to hand out data from inside the fortress to the outside world, if asked just right. If your API were in the physical world, it might look something like this:

“Tap out ‘shave-and-a-haircut-two-bits,’ then the morse code for your name and return address, and a description of the data you want. We’ll either FedEx you a list or FedEx you a note saying you asked for data we’re not willing to give you.”

• Thirdly, you might set up communications protocols for both directions of data transfer, to really facilitate 2-way conversation.
  • Note, though, that every piece of that conversation is initiated by some “outsider” piece of software knocking on your fortress’s door in a specific way, no matter which way the “data you care about” is flowing.

2: “Endpoint” Inside Salesforce, Built By Salesforce

There’s ALSO a general-purpose API, built into every Salesforce database (“org”) in existence, that uses the “REST” communications protocol.

Salesforce defines and maintains how it works.

It’s a door that Salesforce the corporation cut into your fortress and posted a guard at.

This “API” is what the authors of “ETL” tools like Data Loader & dataloader.io & Jitterbit & Zapier study carefully before writing such tools.

Technically, you can write your own tool taking advantage of this protocol, but most people don’t bother, since other companies have done such great work.

• In the worlds of Pardot and Marketing Cloud, 3rd-party tools are harder to find, so it’s rather common to use approach #2 and program against the API that they provided.
  • That’s what my “Python for Pardot / Marketing Cloud” posts have done so far.
• If you choose approach #1, you can sometimes INSERT more data in fewer “API calls” than you could with approach #2 or 3rd-party tools.

Both approaches #1 & #2 give you the chance to write code inside your Salesforce database that post-processes incoming data according to your business’s needs.

• With approach #1, you might bundle “data post-processing logic” into the back end of the API for efficiency.
• With approach #2, you have to use “process builders” and “workflows” and “flows” and “triggers” and such to handle any “data post-processing logic.”

3: “Call” A 3rd Party’s “Endpoint” Living Outside Salesforce

Finally, you can write Apex code within your Salesforce org that goes knocking on the doors of OTHER fortresses.

Doing so might involve writing Apex that uses the “REST” protocol and someone else’s “API,” but it’s not at all the same thing as the 1st concept we discussed.

When learning how to do this, you’ll often hear terms like “writing asynchronous Apex” and “making HTTP requests with Apex.”

How They’re Used In Production

Approaches #1 & #2 have a lot in common.

Both have an “endpoint” inside your Salesforce “fortress.”

Both require similar levels of developer skill.

• #1 might be more favored by your in-house web developers.
• #2 might be what your in-house database developers stumble onto when they read official Salesforce documentation.

To decide which approach suits your business needs better, ask yourself:

1. Do you prefer to be constrained to programming in Salesforce’s “Apex” langauge, yet have more control over Salesforce database performance? You might prefer approach #1 (“build your own API”).
2. Do you prefer to have more control over the language in which you program your data integration? You might prefer approach #2 (“use the API Salesforce built”).

Pro Tip: If you use approach #1 (cutting your own holes in your fortress wall), make sure your non-Salesforce in-house programmers know about the existence of these “endpoints” so they don’t waste their time reinventing the wheel with approach #2!

Most everyday Salesforce data integrations take the form of approach #2, but you wouldn’t know it.

If you’ve ever used a 3rd party’s “ETL” tool to connect outside data to your Salesforce org, you indirectly leveraged approach #2.

However, you probably haven’t talked about it, at a business level, as “using an API.”

Therefore, this note is a moot point / nerdy trivia.

Security: “apps” & “packages” in your org

From a security standpoint, it’s important for you to know that:

1. Some “apps” you install in your Salesforce org might use “approach #1” as part of the software package they deliver to you (that is, they might cut a hole in your fortress and post a guard).
2. Some “apps” you install in your Salesforce org might use “approach #3” as part of the software package they deliver to you (that is, they might go knocking on 3rd parties’ doors on your behalf).

Takeaway

When talking to developers about Salesforce integrations and APIs, ask them what they mean!

• Do they mean making “knock-knock” requests at the door of your Salesforce org?
  • If so, do they plan to cut their own door into your fortress or use the one Salesforce already established?
• Do they mean programming your Salesforce org to knock on other fortresses’ doors?

These questions will help you ensure that everyone on your team understands each other as you plan important architecture and security decisions.