OCAPI URL Syntax

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.

The base URL has a different structure depending on whether you’re 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:

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

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).

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:

The second addresses a single resource using an identifier:

The third addresses resource information by specifying an action:

The fourth addresses multiple instances of dependent resources:

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

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

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

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:

Resource types ({resource_type}) are fundamental to the Open Commerce API, as they’re 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}):

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

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/v24_5/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.

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:

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

Actions ({action}) operate on specific resource types ({resource_type}) and relationship types ({relationship_type}). Actions aren’t 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):

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:

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