Skip to main content

Introducing the Salesforce Commerce SDK

Josh Begleiter
Feb 27 - 5 min read

Introduction

Over the last six months we’ve been working on something new and special here at Salesforce B2C Commerce. Salesforce B2C Commerce has undertaken the behemoth effort to enable our customers to go headless, and to do so we’ve engineered a brand new service platform with an API-first approach, sample apps to demonstrate their use, and a software development kit (SDK) to easily utilize all the new services, each with a strong focus on developer experience. All of our new services are built against best-in-class API standards using Mulesoft. Our team was responsible for the creation of this SDK and much of the developer experience. We’re excited to present here, for the first time ever, a walkthrough of our open source Salesforce Commerce SDK.

APIs are Paramount

Before we get into the SDK, let’s talk about what makes a good interface. The SDK is a reflection of the APIs with which it interacts, and, while this might seem obvious, if the APIs are not clean, interactions with them will not be either. The first task here, then, is to holistically look at the collection of APIs for which we are planning to build an SDK. We started by asking ourselves the following about the APIs:

  • How can these APIs be organized in a way that makes sense to an outsider?
  • What are the cross-cutting configurations of the API ecosystem?
  • Do the API definitions feel cohesive?
  • How will a client SDK map to the APIs?
  • What exceptions/edge-cases are there?

With this in hand we were able to map the APIs to an SDK for what we feel is a much nicer result than without this rigorous planning.

Goals of our SDK

There’s an incredible complexity to running a commerce storefront that is invisible to shoppers, and, as a result, we offer a vast depth and breadth of features through Salesforce Commerce Cloud. These features are grouped into APIs, and then into API families, which can be reviewed through our Commerce Cloud Developer Center (CCDC). In order to wrangle this complexity we are committed to a strong focus on the developer experience, which means writing well-supported documentation, providing channels for questions, feedback, and issues, and enabling our developers, both internal and external, to easily communicate with the APIs.

To accomplish this we created the sample application and components that are powered by the Salesforce B2C Commerce SDK, and our SDK has specific, research-backed goals in order to make building Salesforce B2C Commerce applications easy. Our SDK must:

  • Be simple, straightforward and make it easy to get started
  • Mirror the functionality of the APIs, making clear links between functionality and documentation
  • Provide helpers (syntactical sugar) to make common usages and patterns easy and repeatable (e.g., caching, auth, etc.)
  • Remove as much boiler-plate code from the developer workflow as is technically possible (e.g., header management)
  • Provide IDE integrations such as type-ahead

Using our SDK

Organization

Today we have approximately 175 endpoints in Salesforce B2C Commerce APIs, and we need to organize those APIs in a logical and consistent fashion. We previously mentioned the relationship between APIs and API families, an example of which might look like the following:

  • Checkout
  • ShopperBaskets
  • ShopperOrders
  • Orders

This provides a logical organization of the APIs to make whatever you’re looking for easier to find.

We also have two exports from the SDK that are not API families or clients, helpers and ClientConfig. These are utilities that came out of a need for simplified workflows.

Configuration

ClientConfig is a class that enables a developer to configure all client instances with configuration details that are standard across most, if not all, of our API families. The parameters object therein contains the following options:

let clientConfig = {
parameters: {
organizationId: "org_something_001",
shortCode: "yourshortcode",
siteId: "yoursiteid",
clientId: "yourclientid"
}
};

Note that the parameters listed above are for illustrative purposes only, the values of which do not reflect reality.

Authentication

All of our API endpoints require authentication. Knowing this, we had an explicit goal to make AuthN as simple as possible, since every application will use it. Among our APIs, there are two kinds of authentication. We tend to think of them as shopper authentication (used for “Shop” APIs) and data authentication (used for “Data” APIs). In this article we are going to focus on shopper auth. Shopper auth already exists as its own endpoint, which can be found in “Customer.ShopperCustomer.authorizeCustomer.” In order to make things easy and simple we’ve created the aforementioned “helpers” that exists to make common usage patterns easy, e.g.:

helpers.getShopperToken(clientConfig,{type: "guest"}).then(token => {
commonClientClientConfig.headers = {
"Authorization": token.getBearerToken()
}
...
});

Behind the scenes, this is creating the client, making the API call to the authentication endpoint, parsing the response headers, and finally mapping the response to a simple “ShopperToken” object. This does the heavy lifting so you don’t have to.

Making a Call to an API Endpoint

As a wise person once said, “making things easy is hard.” Once we’ve set up the configuration and the authentication, then all we need to do is create the clients we desire. For example, let’s say we want to get information on an iPod shuffle from our product API.

let productClient = new Product.ShopperProducts(clientConfig);productClient.getProduct({
parameters: {
id: "ipod-shuffle"
}
}).then(productInfo => {
console.log(productInfo);
});

Above, the productClient makes a call to the getProduct API, taking only an ID and returning a promise of type product.

Easy!

Open Source and Updates

In general, and as part of this initiative, Salesforce is committed to open source and providing transparent, frequent updates to our open source software. We love to hear from developers and strongly recommend that you sign up for and use a CCDC account in order to post questions in the forums. We also periodically review Github issues. As part of our contribution model we may even merge upstream from downstream forks!

At Salesforce, Trust is our #1 value. We believe that the developer community needs to be involved directly in the development of our SDK. You can see how our SDK is built, employ our best practices, receive important updates, and communicate feedback easily.

Try it Today!

Being an open source project means that anyone can review our best practices and try the Salesforce Commerce APIs using our SDK without signing a contract. This is made possible by the built-in mocking services that Mulesoft provides. We invite you to review the documentation and our getting started guide today and reach out with any questions or comments.

Related Architecture Articles

View all