Salesforce B2C Commerce 24.7 > Open Commerce API 23.2 > OCAPI Usage 23.2

OCAPI URL syntax 23.2

The Open Commerce API uses a specialized schema for its URLs, and each URL consists of a base URL and an extended URL. The base URL is the same for all API requests; the extended URL changes depending on the resource and the operation. To access the Open Commerce API's functionality, you construct URLs as described below.

Base URL

The base URL has a different structure depending on whether you are using a production instance or a non-production instance (including staging, development, and sandboxes). For a production instance, the base URL has the following structure:

http(s)://public_domain[/s/site_id]/dw/api_type/

For more information about aliases, see Hostname Aliases. For a non-production instance, the base URL has the following structure:

http(s)://<domain>/s/site_id/dw/api_type/

where api_type is either shop, data, or meta; public_domain is the DNS name mapped to the Commerce Cloud Digital site (for example, www.example.com); and site_id is the ID of the actual site to be used (for example, SiteGenesis).

Extended URL

The base URL provides the main access point of the Open Commerce API. You extend the base URL to access specific resources. When you extend the base URL, you must conform to the following patterns. The variables shown in these patterns are described below.

The first pattern addresses multiple resources of a resource type:

base_url/version_id/resource_type

The second addresses a single resource using an identifier:

base_url/version_id/resource_type/identifier

The third addresses resource information by specifying an action:

base_url/version_id/resource_type/action

The fourth addresses multiple instances of dependent resources:

base_url/version_id/resource_type/identifier/relationship_type

The fifth addresses information from a dependent resource by specifying an identifier:

base_url/version_id/resource_type/identifier/relationship_type/relationship_type_identifier

The sixth addresses information from a dependent resource by specifying an action:

base_url/version_id/resource_type/identifier/relationship_type/action

Note: Use only ASCII characters in your URLs; escape any reserved ASCII characters by using the common "%" notation.

Version ID

The version_id specifies the API version. Each API version supports a set of resource types (resource_type), resource properties, relation types (relationship_type), and actions (action). A new API version can add new resource types, add properties to existing resource types, deprecate previously supported resource types, and introduce new semantics or behaviors without introducing structural changes.

The version_id starts with the character "v" (lowercase) followed by the actual version number, separated by an underscore. For example:

http://example.com/dw/shop/v23_2/resource_type/identifier

Resource type

Resource types (resource_type) are fundamental to the Open Commerce API, as they are to any RESTful API. Each resource type has a corresponding set of data: properties, relationship types (relationship_type), and actions (action). An instance of a resource type is analogous to a Digital object, such as Product or Basket.

The Open Commerce API provides a fixed set of system resource types for each API version. Resource types that provide access to multiple resources are given plural names (for example, "products"). Resource types that provide access to only one resource are given singular names (for example, "site"). The following example URL retrieves resources of type products using an identifier (identifier):

http://example.com/dw/shop/v23_2/products/identifier

Identifier

Unique identifiers (identifier) enable you to request specific resource instances. The following URL searches for product resources using an ID (typically a SKU):

GET http://example.com/dw/shop/v23_2/products/123FOO456bar

The identifier must be URL encoded. The following encoded URL escapes a reserved ASCII character (the "#" character in "foo#bar"):

GET
                        http://example.com/dw/shop/v23_2/products/foo%23bar

When you specify a value for identifier, make sure the value conforms to the following restriction:

All values for identifier are case-sensitive.

Multiple Identifiers

Some resource types, like products, support the request of multiple resources by specifying multiple identifiers in the request URL. When responding to such a request, the Open Commerce API returns a result object that includes an array of the requested resource documents.

The following example shows how to request multiple product resources:

GET http://example.com/dw/shop/v23_2/products/(123,456,789)

You must enclose the comma-delimited list of identifiers within parentheses.

Action

Actions (action) operate on specific resource types (resource_type) and relationship types (relationship_type). Actions are not generally available across all resource types and relationship types. Actions perform special operations―for example, customer login.

The following example URL uses an action to authenticate a customer (this action is specific to the customers resource type):

POST http://example.com/dw/shop/v23_2/customers/auth

Relationship type

A relationship type (relationship_type) represents a resource type that depends on another resource type (resource_type). Relationship types enable the API to model one-to-many relationships between a single resource (for example, a Product) and multiple dependent resources (for example, ProductLinks). Each resource type can define a subset of relationship types, which are unique to the resource type.

The following example URL requests items for a basket:

GET http://example.com/dw/shop/v23_2/baskets/12345/items

This request returns all items for the basket with the ID "12345".

X OCAPI versions 15.x and 16.x will be retired on March 31, 2021. For dates and more information, see the OCAPI versioning and deprecation policy and this Knowledge Article.