API Fundamentals: Navigating the Basics

In a recent professional development series, we introduced some of our team to the world of APIs. We actually tailored these discussions specifically for our go-to-market consultants rather than our developers…why? Well, let’s face it –  APIs can be a tough nut to crack, especially if you haven’t been immersed in them day in and day out for a significant period. Given their immense importance in the tech world, it’s easy to feel overwhelmed trying to figure out where to even start. The information out there can be intricate, complex, and, let’s be real, a little intimidating, even for those with technical know-how.

While our consultants do boast technical backgrounds, we’re always aiming to empower and equip them with the tools and insights necessary to assert control over their Salesforce projects and to deepen their understanding of crucial technical concepts. With knowledge on this topic specifically, they’re able to streamline technical tasks for clients, fostering a deeper understanding of the workings of APIs within the Salesforce ecosystem.

In this article, we’re going into the fundamentals of APIs, HTTP requests, authentication types, and their significance in the Salesforce context.

Goals of this article:

  • Get a basic understanding of how HTTP Requests work.
  • Have a basic understanding of available Auth types.
  • Understand what is required to communicate externally from SF Instance.
  • Use Postman to test a request/response from a simple API.

What is an API?

Before we dive into the intricacies, let’s start with the basics. An Application Programming Interface, or API, is a broad term that encompasses various means of communication between software applications. In the context of our recent team discussions and this article, we’ll focus on web server APIs, which facilitate communication between systems or websites to exchange data. Essentially, it’s how one computer or web server interacts with another to retrieve or transmit information.

Think of APIs as the language that computers and web browsers use to communicate with each other. They define the rules and protocols for this interaction, ensuring seamless data exchange and interoperability across different platforms and systems.

Fortunately, tools like Postman simplify the process of working with APIs. Postman provides a user-friendly interface for sending and receiving HTTP requests, making it easier for developers and consultants alike to test and interact with APIs without having to write code from scratch. With Postman, even those with limited technical expertise can navigate the complexities of API communication with confidence and efficiency.

What is an HTTP Request?

At the heart of API communication lies the HTTP request. Hypertext Transfer Protocol or HTTP, is the foundation of data communication on the web. An HTTP request is a message sent from a client to a server, specifying the action to be performed and any additional data required. Understanding the anatomy of an HTTP request is essential for navigating the intricacies of API interactions.

When a computer communicates with a website or server, it typically requests to either retrieve or store information. These requests consist of essential components including the URL, method, headers, and body (if applicable). The Uniform Resource Locator, or URL, specifies the website or endpoint to which the request is being made.

Source: Realisable // Edited by: Lane Four

In the Salesforce consulting or admin context, you’ll primarily rely on the GET and POST methods, with occasional use of PUT, PATCH, and DELETE. Headers hold essential details about the request, including authentication credentials, whereas the body contains the information being transmitted to the server, although the body is not mandatory for GET requests.

HTTP Methods

Why Should I Care? I'm Not a Developer.

You might be wondering why APIs matter to you as a Salesforce consultant or admin. The truth is, APIs are more than just a developer’s tool—they serve as a foundational knowledge base that empowers proactive and prepared consulting work. This knowledge not only allows you to gather specific requirements and information before engaging with a developer, thus saving valuable time and cycles, but it also facilitates the smoother handoffs and streamlines this process.

In simpler terms, introductory or general knowledge about APIs can speed things along. Additionally, with the HTTP Callout Node for Flows recently becoming generally available, there is a promising future where consultants can autonomously leverage APIs, further enhancing efficiency and autonomy in Salesforce projects. While you may not always foresee the immediate application of API knowledge, you’ll undoubtedly appreciate having it when the need arises!

Authority Types

When it comes to accessing APIs, authentication is important. Authentication types determine who has access to the API and what actions they can perform. From basic authentication to OAuth2.0, each method comes with its own set of advantages and considerations. By familiarizing yourself with authentication types, you can ensure secure and compliant API access for your Salesforce projects.

  • No Authentication
    • Open API
    • No credentials needed!
    • Not too common
    • Even public data APIs usually require credentials for auditing and rate limiting purposes
  • Basic Authentication 
    • A username and password that’s sent in the headers
    • Not very secure but simple and easy to use and build
  • Key/Secret
    • A secret or key stored that’s simply checked on the server
    • Also not as secure but even simpler than basic auth
    • Sometimes, the key can be a more secure encrypted token that stores actual information
      • Like basic auth susceptible to man in the middle attack
  • OAuth
    • A more complex flow of generating tokens that expire via preliminary requests, then sending those tokens in the headers for the request you’re trying to make
    • Out-of-the-box ways to handle the retrieval of tokens and adding it to your headers
    • Auth Tokens can not be reused
    • Unless you’re familiar and comfortable working with OAuth best to engage with a dev at this point

Let’s Talk Salesforce!

Now, let’s bring it all back to the Salesforce context. Whether you’re integrating third-party applications, automating business processes, or extracting data for analysis, you may stumble across APIs. By understanding APIs and how/where to configure them in Salesforce, you can streamline workflows and deliver exceptional results for your clients.

  • Named Credential – Sets up a reference to the base URL for the API, both Apex and the HTTP Flow node will use this to know which URL to use
    • “Use [Web Service Name] API”
  • External Credential – Handles the authentication for the Named Credentials 
    • You will need to grant any user who’s action will callout to the API access via a permission set
  • Permission Set – Grants the user permission to the External Credentials
  • Auth Provider – Stores a bunch of details for handling OAuth, Salesforce then handles all the authentication for you
    • Can also be used to handle Social Sign On for both your internal and community users
  • User Context – For OAuth, allows you to call the API as the acting user instead of just the Salesforce system

Real Life Use Case for Our Consultants: 

In scenarios where integration with an API is necessary and clients provide authentication information, possessing API knowledge empowers Salesforce consultants to independently verify this information. Furthermore, it enables them to ensure that the received response contains the required data or that they can successfully transmit the necessary information as per project requirements.

Exploring Further with Postman

Ready to put your newfound knowledge of APIs to the test? Enter Postman, the go-to tool for testing API requests and responses. Postman simplifies the process of interacting with APIs, making it an essential tool for developers, consultants, and anyone else looking to dive deeper into the world of API testing.

To get started with Postman:

  • Launch the application or Postman in your browser, create an account, and login
  • Create a new Workspace if it’s your first time!
  • Create a new request by specifying the request method (e.g., GET, POST), URL, and any required headers or parameters.
  • Hit the “Send” button to execute the request and view the response in various formats, including JSON, XML, and HTML.
  • Use Postman’s built-in features, such as test scripts and collections, to organize and automate your API testing workflows.
  • Experiment with different request types, authentication methods, and parameters to gain a deeper understanding of how APIs work.

A fun exercise to try: Select the GET Method and Enter http://catfact.ninja.fact
for the URL, click Send, and see what you get!

By gaining a basic understanding of APIs, HTTP requests, authentication types, and their relevance to the Salesforce context, you can become a more proactive and effective consultant, capable of driving success and innovation in your Salesforce projects.