There are two main APIs for Data Cloud: the Data Cloud API (formerly known as the Direct API) and the Data Cloud Connect API. Some of the features of these two APIs overlap, but the APIs have distinct use cases and performances because they rely on a different architecture. In this post, we’ll cover the key differences between these two APIs, and we’ll share how you can explore them using the recently refreshed Postman collections.
About Data Cloud APIs
The main difference between the two Data Cloud (DC) APIs is their architecture as illustrated in the diagram below.
When using the Connect API, you interact with the Salesforce Platform which will in turn query the DC tenant. Using the Connect API is interesting when you’re mixing platform and Data Cloud operations because you can share the same connection. For details about the resources that the Data Cloud API and the Data Cloud Connect REST API can access, see Data Cloud Development Overview in the Data Cloud Developer Guide.
When using the Data Cloud API, you first authenticate with the platform and you request a DC tenant authorization token (Step 1 in the diagram above). Then, you can issue API requests to the DC tenant with the authorization token (Step 2). This API requires an initial token exchange request, but this architecture results in faster operations as you’re directly hitting the DC tenant (thus the former “Direct API” name). There’s also an important difference with the Connect API: with the exception of the Ingestion API, the Data Cloud API only offers read operations.
The best way to explore these two APIs is to use Postman and our dedicated collections.
Note: Data Cloud APIs are subject to limits and billable usage. For more information, see the “API Guidelines and Limits” section in Data Cloud Limits and Guidelines in Salesforce Help.
Exploring the Data Cloud API Postman collections
About Postman
Postman is an API platform that includes several tools, such as a client for HTTP-based APIs, WebSockets, gRPC and more. It’s a very convenient and powerful tool that leverages point and click configuration. API requests can be saved as templates in a collection, so that they can be quickly shared among users and reused. The tool supports environment variables, team workspaces and JavaScript automation, among other useful features. Postman can be used from a desktop app or from a web browser.
Salesforce hosts a dozen API collections for various products in the Salesforce Developers workspace, including Platform, Data Cloud, Tableau, MuleSoft, Commerce Cloud, and Marketing Cloud.
What’s new in Postman Data Cloud API collections
We first introduced a Data Cloud collection (formerly known as Customer Data Platform or CDP) in early 2021. Since the beginning of 2024, we’ve been working on a major refresh of these resources.
Logical structure
The first and most visible operation that we performed was to split the original DC collection in two: one for each API type. The split made sense from a documentation standpoint (each API has its own documentation) and this would allow us to work easily with dedicated authentication flows.
Simpler authentication
Both APIs can use any of the supported authentication modes to authenticate with the Salesforce Platform, such as the OAuth authorization flows. In prior versions of the DC collections, we were using an OAuth JWT authentication flow which required that you set up a connected app and a certificate. While this is the most secure option for production, it was a lengthy and error prone setup for a developer tool.
Thanks to your feedback and our experience with the Salesforce Platform APIs collection, we switched to a much simpler authentication process that involves a shared connected app, an OAuth implicit grant flow, and some scripts. With these changes, authenticating only takes a couple of clicks and a few seconds instead of a lot of configuration and 10+ minutes (if all went well).
The process is documented for each collection:
- Data Cloud Connect REST API: instructions and video
- Data Cloud API: instructions and video
Fewer collection variables with clearer names
As a byproduct of the collection split and the authentication simplification, we were able to drastically reduce the number of variables that were used by our collections, and this made them easier to configure. We also refactored variable names and introduced a naming convention that helps users better understand the purpose of the variables while identifying which are set manually or programatically.
Additional requests
Since we’ve split the two collections, we’ve added a number of API sub folders and requests, such as the Query API v2 and the Data Graph API for the Data Cloud API, or the Data Graphs and Connections request groups for the Data Cloud Connect API.
Response examples
Most API request templates now feature response examples that can help you quickly assess the structure of the response without even running the request.
Conclusion
We hope that you’re as excited as we are with these enhanced Data Cloud API Postman collections. Head over to the Salesforce Developers Postman workspace to get started with the collections, and watch the intro videos to familiarize yourself with the APIs. If you don’t yet have a Data Cloud environment, remember that you can obtain a temporary playground from Trailhead. Happy API exploration with Data Cloud, and don’t hesitate to spread the word and contribute to the initiative!
Resources
- Data Cloud Reference Guide
- Data Cloud API documentation
- Data Cloud Connect API documentation
- Salesforce Developers Postman workspace
About the author
Philippe Ozil is a Principal Developer Advocate 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 with APIs, DevOps, robotics, and VR projects. Follow him on X and LinkedIn, or check his GitHub projects.