Explore Open Commerce API (OCAPI)

Learning Objectives

After completing this unit, you’ll be able to:

• Explain the functions of the OCAPI API types.
• Explain how HTTP methods work.
• List three functions of the client ID.
• Describe the OCAPI URL schema.
• Explain the function of the resource state.

What’s OCAPI?

OCAPI enables developers to work with all the resources (such as baskets, customer data, and products) that they used with the Commerce APIs, but via HTTP requests and responses. Each HTTP resource is addressed by its unique URL. Data is transported using request or header parameters, or within the request body as a JSON document with a defined structure.

OCAPI is a representational state transfer (REST) application programming interface (API) where the client initiates the transfer of representations of the server state.

OCAPI includes three types of RESTful APIs.

Follow these steps to get started.

1. Learn about HTTP methods.
2. Get a client ID.
3. Review schemas.
4. Learn about resource states.
5. Configure OCAPI settings.

Use the API Explorer (credentials required) to browse the API and run test requests. Use the Salesforce documentation to understand resource details.

HTTP Methods

OCAPI accesses resources with HTTP requests and HTTP responses. Each resource is addressed by a unique URL, and includes the API version. Data is transported using request or header parameters, or within the request body as a JSON document with a defined structure. RESTful Web APIs use HTTP methods, as defined by RFC 2616. OCAPI supports these.

The PUT method lets you create a resource with the identifier specified in the URL. Use POST when the identifier is provided by the server.

Take a look at OCAPI HTTP Methods for method usage details.

Override HTTP Methods

Some web frameworks, such as AJAX frameworks, support only GET and POST requests. OCAPI works around this by supporting POST requests that override the HTTP method with the DELETE, HEAD, OPTIONS, PUT, and PATCH methods. Just specify the explicit request/form parameter method with the value of the overriding method in upper case. Here’s an example.

REQUEST:
POST /dw/shop/v21_10/products/123?method=DELETE HTTP/1.1
Host: example.com
Accept: application/json
RESPONSE:
HTTP/1.1 204 NO CONTENT

You can also override a method by specifying the B2C Commerce HTTP header x-dw-http-method-override with the value of the overriding method in upper case.

PATCH, POST, PUT with Empty Request Body

Some PATCH, POST, and PUT OCAPIs don’t require a request body. But making these calls with empty request bodies can cause problems such as HTTP 500 responses. To prevent this, provide the Content-Length request header with the value 0, as shown in this example.

REQUEST:
POST /dw/shop/v21_10/sessions HTTP/1.1
Host: example.com
Content-Length: 0

Take a look at the status code and faults you might see in HTTP responses in Salesforce Help.

Client ID

OCAPI requires that all client applications use a client ID. It must be appended to the URLs used to interact with OCAPI. You can’t use the same client ID for OCAPI calls and Salesforce Commerce API (SCAPI) calls. An API Client ID that’s meant for OCAPI cannot be assigned the Salesforce Commerce API role.

Administrators use Account Manager to create API clients. To access Account Manager, you must have a B2C Commerce implementation. Here’s how to add an API client.

1. Open Account Manager.
2. Click API Client.
3. Click Add API Client.
   
4. Enter the client’s display name.
5. Enter the password twice.
6. Locate the organization where you want to add a client, select it, and click Add.
7. Click Save.
8. Select API Client in the left navigation menu.
9. Verify that the new client ID is enabled.

URL Schema

OCAPI uses a specialized schema for its URLs, where each URL consists of a base URL and an extended URL. The base URL is the same for all API requests, while the extended URL changes depending on the resource and the operation.

Base URL

The base URL structure depends on whether you are using a production or a non-production instance (staging, development, or sandbox).

Here’s the difference.

Here’s what the parameters mean.

Demandware.net

Do not use production - or development- hostnames to access OCAPI or the storefront. For example, do not use production-xxx.demandware.net or development-xxx.demandware.net. Instead, use a vanity hostname such as brand.com or www.brand.com. As of August 2022, development and production instances will automatically reject these calls.

For example, if your calls to URLs look like this: 

https://production-realm-customer.demandware.net/s/Sites-SiteName-Site/dw/shop/v20_10/product_search.

They should now look like this:

https://www.example.com/s/Sites-SiteName-Site/dw/shop/v20_10/product_search

Customers can still access Business Manager at production-realm-customer.demandware.net.

Extended URL

While the base URL provides the main OCAPI access point, you can extend it to access specific resources. Use these patterns in this order to extend the base.

Use only ASCII characters in the URLs. Escape reserved ASCII characters with the % notation.

Here are the parameters.

• version_id: API version
• resource_type: Set of data properties, relationship types, and actions
• identifier: Specific resource instances
• action: Operation on specific resource and relationship types
• relationship_type: One-to-many relationships between resources
• relationship_type_identifier: A resource type that depends on another resource type

Resource State

A resource state represents the server-side state of a specific resource such as a basket or a customer. It’s a string token that’s used in all the resource property information.

OCAPI exposes resource state information via the _resource_state property in the response body. The response contains either a single resource state or multiple resource states when calling a collection or search resources. With body-less responses (for example, HEAD) the resource state is exposed via the x-dw-resource-state response header. When a resource state is part of a client's request, OCAPI verifies it by comparing its value with the server resource state.

You can pass a resource state to any state changing method (DELETE, PATCH, POST, PUT). If no resource state is passed, the resource is overwritten, updated, or deleted without further notice based on the default HTTP method behavior. For more details on resource states, see Salesforce Help.

OCAPI Settings

You configure OCAPI settings in Business Manager, via an embedded JSON file that conforms to a certain format. Settings include client details and resource-specific permission and settings. See Salesforce Help for format details.

You can define settings and permissions for a single site or for all sites. You can override global settings for the client ID per site. Most Data API resources are organization-specific, so they support only global permissions. Settings are cached for up to three minutes until they become effective.

Here’s how to edit OCAPI settings in Business Manager.

1. Open Business Manager.
2. Select Administration > Site Development > Open Commerce API Settings.
3. Select the API type for the configuration: Shop or Data
4. Select the context for the configuration: Global (or site-specific)
5. In the text field, edit the JSON document.
6. Click Save.

Let’s Wrap It Up

In this unit, you learned how OCAPI, a RESTful API, lets you customize a B2C Commerce storefront via HTTP requests. All you have to do now is take the quiz and earn an awesome badge.

Resources

• Salesforce Help: Add an API Client
• Salesforce Help: OCAPI URL Syntax
• Salesforce Help: OCAPI Resource States
• Salesforce Help: OCAPI Settings
• Salesforce Help: OCAPI Caching
• External Link: RFC 2616 Hypertext Transfer Protocol - HTTP/1.1