Explore the Salesforce APIs with a Postman Collection

Salesforce exposes a rich set of APIs that lets you integrate your org with third party systems in a great variety of scenarios. All of these APIs are thoroughly documented, but how can you quickly try them on a given org – or better yet, on multiple orgs?

In this post, I’ll introduce you to Postman and show you how to easily explore and test different Salesforce APIs against multiple orgs using an open source Postman collection (that I’ve already assembled for you). This unofficial collection currently holds close to 200 API call templates for 10 Salesforce APIs (REST, Bulk, UI, Tooling, Metadata and Composite just to name a few).

About Postman
Postman is a desktop application that lets you configure and call HTTP-based APIs like REST or SOAP. It’s a very convenient and powerful tool that leverages point and click configuration. It supports environment variables, team workspaces and JavaScript automation among other useful features.

Exploring and Testing APIs With Postman

As a Technical Architect, (and like most developers) I often configure and troubleshoot API calls. I configure and compare those calls on multiple environments (sandboxes, production orgs…) then share the results of my findings. In order to do that, I use a couple of tools.

There are several Salesforce and third party tools that let you explore and call APIs. I’m not going to list them all here but a a classic go-to solution for developers is Workbench. Workbench lets you execute Salesforce API calls against all types of orgs directly from your browser. This tool was created by the community and is now operated by Salesforce, but it’s not officially supported and only receives security updates. Workbench is a great tool to explore the Salesforce APIs and run one-shot tests. However, it has several limitations for a broader use: it doesn’t allow you to save your configuration, reuse it on multiple orgs or collaborate.

Since Workbench didn’t cover all of my needs, I started using Postman to troubleshoot API calls. Unlike Workbench, it’s not tied to Salesforce technology but it has several great advantages:

• It gives you full control over HTTP requests. There’s no file upload limit; you can set headers and parameters, and use any content type (binary, text…)
• You can switch between multiple environments. For instance, you can have an environment for production and another one for a sandbox. When switching environments, all variable values are updated to environment-specific values.
• If you use the free version of Postman, you can collaborate on requests by importing/exporting your workspaces. There are also paid plans that couple Postman with source control for live collaboration.
• You can automate things by building post execution scripts with JavaScript. That can be used for setting environment variables.
• You can generate code snippets for a great variety of languages from your requests. Here’s an example of how you can retrieve your Salesforce API limits by calling the REST API with the JavaScript Fetch function:

Postman helps me quickly design and reuse API requests across projects. As the number of reusable requests grew, I decided to create an open source Salesforce APIs collection.

Introducing the Salesforce API Collection

Collection Overview

Salesforce APIs for Postman is a collection of requests for Salesforce APIs. The collection includes hundreds of request templates grouped into folders (one per API), a template environment with variables and header presets.

Building from API request templates instead of going into each API’s documentation saves you a lot of time and greatly reduces the risk of errors. However, just like Workbench, the Salesforce APIs Collection doesn’t replace the documentation. You’ll need to use Postman in combination with the API’s documentation.

An advantage of Postman over tools like Workbench is that it allows you to explore a variety of Salesforce authentication flows. The Salesforce APIs Collection lets you try these different flows: you can try the SOAP login flow, OAuth username/password flow, JWT Bearer Token flow and other flows. That’s particularly interesting when working on integrations.

When working on a project, I usually maintain a Postman environment per org. I start by cloning the template environment and fill in the first five variables for each org: url, version, username, password and secret token. This way I can quickly use the SOAP login flow then build and call APIs using the Salesforce API Collection. Then, later on, I can easily switch to another environment and use the same requests.

Let’s see how easy it is to use the collection with an example.

Sample Use Case : Inserting an Attachment on a Case

Before jumping into the example, make sure to complete the following pre-work:

1. Install Postman.
2. Import the Salesforce APIs Collection and follow the project readme for instructions.
3. Clone the template environment and configure it with your org’s credentials.
4. Log into your org using the SOAP Login flow in order to validate your settings.

For the purpose of this sample use case, you’ll be in the shoes of a developer working for Acme Inc., a fictitious company that sells goods and manages its operations using the Salesforce Platform. Acme Inc. provides a mobile application to its customers to allow them to create cases about the products they receive. The application lets customers upload a picture of the packages they receive and attach it the cases. Your goal is to provide the configuration of the Salesforce REST API call that will be used to upload the image as an attachment to a case.

As always, a good start is to head for the API documentation in order to learn about the request’s usage and the required fields (Name, ParentId, and Body for this request).

Now that you know more about the API request, let’s create it in Postman:

1. Create an Acme collection to regroup your custom requests.
2. Select the REST > SObject Create request from the Salesforce APIs Collection and duplicate it.
3. Rename the new request to Create Attachment on Case and store it in your Acme collection.
4. Update the endpoint URL by replacing <SOBJECT_NAME> with Attachment.
5. Change the body JSON so that it has a Name, ParentId and Body parameters (as required in the documentation).

Your boilerplate request is ready! Let’s try it out with some real data:

1. Provide a name to the attachment with a Name value.
2. Grab a case Id and set it as the ParentId value.
3. Find a picture. Use a service like this to convert it into Base64 and paste the resulting string as the value of the Body parameter.
4. Hit the Send button and voila! Refresh your case record and you should see your image in the attachments.

You can now:

• Share the new endpoint with your team.
• Replay the request at will in your dev or testing environment and help troubleshoot potential issues.
• Generate and share the code to make this call in several programming languages.

Summary

Now that you know about Postman and this great API collection, follow the getting started instructions and explore the Salesforce APIs. Can’t find the API request you need in the collection? Feel free to contribute to the repository, it’s Open Source!

Co-Author

Philippe Ozil
Philippe Ozil is a Principal Developer Evangelist at Salesforce where he focuses on the Salesforce Platform. He writes technical content and speaks frequently at conferences. He is a full stack developer and enjoys working on robotics and VR projects. Follow him on Twitter @PhilippeOzil or check his GitHub projects @pozil.