I was recently looking to building a prototype integration between Salesforce and Workday, where I find myself needing to on-board with the Salesforce REST API for probably the 50+ time in my career. I am always looking for projects that use the API so that I can keep my skills sharp when it comes to one of the leading API platforms out there. Even with this experience, each time I on-board with the API I find myself having to work pretty hard to make sense of the Salesforce REST API, first wading through a sea of information to get to find the API reference documentation, setting up an OAuth application, and getting to where I am actually making my first API call. Once I am successfully making calls to the Salesforce API, I then have to further explore the surface area of the Salesforce REST API before I can fully understand all the resources are available, and what is truly possible with my integration.
After spending about an hour in the Salesforce documentation it all came back to me. I remembered how powerful and versatile the API is, but my moment of déjà vu left me feeling like it would be pretty easy to reduce the time needed to go from landing on the home page of developer.salesforce.com to making your first API call. The challenge with the Salesforce API is it is extremely large, and possess a number of resources that will vary based upon two important dimensions, version and your user account. The API you see with a base developer account isn’t the same you’ll see with a well established corporate Salesforce implementation. Each individual Salesforce customer might be using a specific version, and have a completely different set of resources available to them, making it pretty challenging to properly document the API. Even with these challenges I think there are a number of ways in which the Salesforce API could be made more accessible for new users, while also improving how existing Salesforce developer engage with the platform—so I wanted to take a crack at building a proof of concept that would help demonstrate the potential.
Salesforce Postman Collection
When using the Salesforce REST APIs there are universal API paths that developers with meta level information about the API, but then there are object specific API resources which provide you with a long list of available resources which you can obtain via the /vXX.X/sobjects/ API path for each version. Then there are a whole suite of object specific API sub-resources you can put to work by simply putting the sObject into the API path vXX.X/sobjects/{SObjectName}/{id}—leveraging path variables to define which individual resource you will be working with. This design pattern is common amongst older enterprise APIs, but it is an approach that can introduce quite a cognitive load when having to learn about what objects are available, and then begin to use them in any intuitive way. To help alleviate the cognitive load for myself when working with the Salesforce API and making it easier for other stakeholders to work with, I generated a Postman collection, and published some simple and more modern API documentation from the machine readable definition.
My goal with this collection was to bring out the potential that is present within the Salesforce API, making it available in a more intuitive and usable way. Using the /vXX.X/sobjects/ API path I generated the Postman Collection, organizing sObjects by folder. The Postman Collection is just a proof of concept and doesn’t reflect all of the available API paths, and is generated from version 20.0 from an entry level develop account. The goal here is simply to autogenerate a Postman Collection for all sObjects for a specific version, organizing all the available API resources into a more coherent collection. Next, I will work on dynamically generating a Postman Collection for each available version, with corresponding objects. Each collection will still reflect an entry level developer account, dynamically generating Postman Collections from the Salesforce API, providing a machine readable collection that can be used by Salesforce and their API consumers throughout the API lifecycle. Providing a machine readable unit of compute for each possible manifestation of the Salesforce API, allowing the API definition shape-shift as necessary to accommodate however Salesforce is being used in the wild.
A Dynamic Salesforce Collection Builder
Providing Postman Collections for dynamic APIs like Salesforce can be a challenge, but this proof of concept demonstrates how more intuitive and usable Postman Collections can be generated from the Salesforce discovery APIs. Providing a dynamic Postman Collection builder can help tame the complexity of the Salesforce API, providing different API paths organized by folder, and published with informative title and descriptions. Helping bring out the diverse number of objects that are available right under the hood, while making the API-enabled actions that are available in a portable, sharable, and executable format that anyone can use locally within their Postman client, or automated via a CI / CD pipelines via the command line. This challenge with API scope and complexity isn’t exclusive to Salesforce, as there are a number of larger data API implementations that have similar design patterns, from financial APIs like Quandl, to healthcare data APIs like OpenFDA. Salesforce is somewhat unique in that it has multiple dynamic dimensions to consider spanning the version, sObjects, and the Salesforce customer installation, configuration, and roles.
Providing Salesforce Workflow Collections
This dynamic approach to generating collections can also be designed to deliver different types of workflow collections, going beyond the reference nature of the Salesforce REST API proof of concept above, daisy-chaining API calls into more coherent business workflows that can be implemented by any developer or non-developer. Providing Postman Collections that deliver upon specific types of business workflows, but are dynamically defined based upon the version of the Salesforce API in use, as well as based upon the specific object available to each individual Salesforce customer. Harnessing the power of the Salesforce API, while taming the complexity of the API, making common everyday business tasks executable as a portable, sharable, and executable format that anyone can use locally within Postman. Further bringing out the value of the Salesforce API out into view, making each individual Salesforce business capability more visible, sharable, and executable as a stand alone Postman Collection.
Instance, Version, and Roles Via Environments
One benefit of using Postman Collection is that you can also abstract away the version, instance, roles, and other variables using Postman Environments, which can then be run against individual reference or workflow Postman Collections. The base URL you use to make API calls to the Salesforce API should always be the first key value pair within any Postman Environment, abstracting away the host of the API as this is what defines the dynamic dimension of your Salesforce customer account. The second key value pair that should be in the Postman Environment is the version of the Salesforce API you wish to be using, providing the second most important dynamic dimension of using the Salesforce API. The third key value pair that should be present is the OAuth Bearer Token for each individual user that will be putting the API to work, allowing for further defining API consumption based upon role. Separating version, user, and role dimensions from each collection, which will ultimately be dynamically generated based upon the sObjects available, and then executed based upon each individual Postman Environment—leveraging collections and environments as the union that absorbs the dynamic and ever changing nature of the Salesforce API.
Providing Salesforce API Mocks
As part of my work on my Salesforce REST API Postman Collection I’m verifying each endpoint by making an actual request and saving the response as an example. Once I do this for each of the 800+ individual API path I can then use them to generate mock representations of the API. Allowing any potential application developer to build against the mocked version of the Salesforce API in a local environment without actually having to develop against the production instance. Once the application is ready, the base URL for the Postman environment can be changed back to the production instance, and the application should work as expected, but instead of mocked examples, it will be working from live responses fro the Salesforce REST API. Providing a personalized and localized experience when it comes to working with the API, further reducing the overhead required for any developer to actually get up and running with the Salesforce API, streamlining the on-boarding with he API as well as the time it takes to actually develop an application.
Publishing Modern API Documentation
Once I have examples saved for each of the Salesforce API paths I can also republish the API documentation I showed above as part of this proof of concept. Publishing the details of each response to compliment the details of each API request I’ve defined. Better organizing Salesforce sObjects as folder, giving them plain language names and description, while also providing details on query parameters, headers, and the example response for each individual API path. In addition to the more cleaner, modern, and complete API documentation, developers also get code snippets in a variety of programming languages including cURL commands for use at the command line interface. Further helping to reduce friction when it comes to on-boarding new users, providing what is needed to get existing developers engaged, and understanding what is happening with a specific version and implementation of the Salesforce API.
API Orchestration With Runners
With my Salesforce REST API reference Postman Collection, and my variety of potential workflow collections I can begin to orchestrate any of the common capabilities I possess to work by executing collections, bundled with different environments using Postman runners. This allows developers to not just manually run API calls, but to daisy chain multiple API calls together in a specific sequence, then execute manually or via a CI/CD pipeline. Allowing Salesforce user to augment what they do through the Salesforce interface via the Salesforce API with well organized Postman Collection defined workflows that help scale and automate beyond what any individual is capable of doing on their own. Demonstrating how Postman Collections aren’t just a machine readable definition of the Salesforce API, but a digital representation of a specific Salesforce capability in the context of a specific Salesforce customer, user role, and version of the API.
API Automation With Monitors
Like runners, monitors can also be setup to execute a specific Salesforce API Postman Collection, allowing different capabilities to be executed in different contexts on any desired schedule, from multiple geographic regions. Monitors can be used to check for specific activity via the Salesforce platform or validating data that has been added, updated, or removed. Monitors can also automate the migration of data between different objects within the Salesforce platform, as well as with any other 3rd party APIs. Defining Postman collections that automate the syncing and migration of data across all of the services that any Salesforce customer depend on—whether it is operated by Salesforce or not. Helping Salesforce developers as well as business users better automate the tasks hey perform on a regular basis in a no-code way.
Keeping The Existing API Life Cycle
What I like most about this idea is it can be implemented without any change to the existing Salesforce API life cycle. It just represents a different way at looking at, and communicating with consumers about the Salesforce API. I can keep iterating upon this proof of concept from the outside-in, and keep evolving my approach to dynamically generating reference and workflow Salesforce Postman API collections and supporting Postman environments without requiring Salesforce to actually make any changes. Ideally, it would be something Salesforce would also invest in and take the reins on, but it is something that can be realized using existing process and Salesforce API paths. Making it a pretty compelling blueprint for reducing friction for Salesforce API consumers, but also potentially other APIs providers that have similar dynamic characteristics in how the API can be put to use, making documenting and on-boarding more harder.
Salesforce Accounts Integration
One area of friction that still exists in this implementation is when it comes to the generation of an OAuth bearer token for each user of a Salesforce Postman API Collections. Each user will need to have their own bearer token to authenticate Salesforce API requests, which currently requires each user to setup a Salesforce OAuth application, something not all consumers will be capable of doing. The concept of what is an application on the Salesforce platform needs to evolved some to accommodate integration platform as a service (iPaaS) and no-code integration opportunities, making it easier for users to generate personal OAuth tokens via their account, like platforms such as GitHub already do. This is something that can be accomplished as part of a 3rd party application or service, but would be something that would have a much wider impact on API adoption and usage of the average developer and business user if Salesforce was to deliver natively via Salesforce accounts.
Organizational API Workspaces
The Postman collection developed as part of this proof of concept contains over 800 individual requests organized by folders—this is a pretty large collection. Ideally it would be organized into much more meaningful groups of collections that reflect different bounded contexts of Salesforce sObjects. Additionally, very granular Salesforce workflow Postman Collections could be developed, providing much smaller, bite sized business capabilities for each Salesforce customer. All of these Postman collections can be organized into separate API workspaces, providing further segmentation of Salesforce API resources which can be powered via a variety of Postman environments published across each of the appropriate workspaces. Logically grouping the organizational capabilities of any Salesforce customer into API workspaces that reflect how business is accomplished by users within a variety of roles.
A Salesforce Collection Template Marketplace
Eventually I’d also like to see the development and publishing of more workflow Salesforce Postman API Collection templates to the Postman template marketplace. Eventually maybe there can be a dedicate Salesforce wing of the Postman template marketplace. Salesforce Postman API Collection templates could be further organized by version and which sObjects they support, allowing for dynamic filtering based upon authenticating with your Salesforce user ID, only surfacing Postman workflow collections that would work for your Salesforce implementation, then potentially also help developers generate an OAuth bearer token and Postman Environment complete with baseURL, ersion, and bearer token. Making many different API workflows discoverable and executable by anyone, allowing any developer or business Salesforce API consumer to put templates from a marketplace to work.
Taming The Salesforce API Scope
The purpose of this story is to help me work through my thoughts around how to make the Salesforce REST API more accessible. I am using it as a scaffolding for my strategy to for iterating upon my dynamic Salesforce API Postman Collection. I am also hoping my approach might catch the attention of the Salesforce team and help them see how Postman can help them reduce friction when it comes to on-boarding with Salesforce REST API, and eventually all of the other APIs they offer via the Salesforce developer portal. I’m hoping it can help convey how Postman can help streamline and modernize the Salesforce APIs, as well as provide a blueprint that can be applied to any other API out there. I just want to provide a straightforward vision of how to evolve how we on-board and communicate around the Salesforce REST API in a way that could be done from the outside-in, or at least without forcing Salesforce to make any changes to their current API life cycle—I know how hard this can be to do. Ultimately I wanted to be able to effectively tame the scope and complexity of the Salesforce API, making it more accessible to new API consumers, but also reduce friction for existing consumers when it comes to putting the very important API to work for them.
Image Credit: Cloud Elements
