OCAPI Settings 19.1

OCAPI settings manage various features, for example, to control OCAPI
client permissions, and to control OCAPI
caching.

You configure OCAPI settings in Business Manager. To specify OCAPI
settings, you edit one or more JSON documents that conform to the format
described later in this topic.

Configuring OCAPI Settings in Business
Manager

To configure OCAPI settings, perform the following
steps:

In Business Manager: Administration > Site Development >
Open Commerce API Settings.

In the Select type field, select the API
type for the configuration.

In the Select context field, select the
context for the configuration: Global for the configuration to affect
all sites in the organization, or the name of a site for the
configuration to affect only that site.

In the text field, edit the JSON document.

Click Save.

Note: You can override global settings for
specific sites. Your settings are cached for up to three minutes until
they become effective.

Site-Specific vs. Global Settings:

Client
settings and permissions can be defined for a single site (site-specific)
or for all sites (global). You can override global settings for Client ID
per site.

Note: Most Data API resources are
organization -specific, so they support only global client
permissions.

Client Permissions:

To use OCAPI, you must first
configure client permissions. These permissions control read and write
access to specified resources. By default, no permission is granted. OCAPI
declines any client application request that does not have the appropriate
permissions, returning an HTTP status of 401 (Unauthorized).

JSON Document Format

The following example shows
the format of the JSON document:

Note: The "_v" property
indicates the version of the configuration file structure. It is
independent of the OCAPI version, and thus allows the configuration of
resources in any OCAPI version.

Configuration Document

Use this
document to configure Open Commerce API permissions for multiple client
applications in the context of a single site.

Property

Type

Constraints

Description

_v

String

N/A

Version number of the configuration file structure. New
versions are created when JSON properties are added or the
behavior of a property changes. Use the most recent version of
the configuration file structure whenever possible.

Resource Document

Use this
document to configure resource-specific permissions and
settings.

Property

Type

Constraints

Description

cache_time

Integer

N/A

Time period in seconds before the response document
becomes stale. The minimum cache time is 0 seconds; the maximum
is 86,400 seconds (24 hours). If no value is specified, the
default is 60 seconds. For more information, see caching.

config

Map<String,String>

N/A

Map that determines which values are returned for some
special response document properties. You control this map by
configuring reserved key/value pairs. For more information, see
Customization.

methods

[String]

mandatory=true, nullable=false

Open Commerce API HTTP method filter. For example, the
filter ["get","patch"] allows access to
the GET and PATCH method for the specified
resource path. You can specify methods that are supported for a
resource. You can list all available resources and methods for
the Shop API, version 19.1, with the following meta data call:
http://{your-domain}/dw/meta/rest/shop/v19_1?client_id={your-client-id}

personalized_caching_enabled

Boolean

N/A

Flag that determines the personalized caching behavior of
a cacheable Shop API resource. By default, the system caches
personalized resources when a customer context (JWT token) is
given. You can use this property to explicitly disable
personalized caching (for example, for performance
improvements). Disable personalized caching only if responses
are guaranteed to be the same for any customer and no further
personalization logic (for example, in hooks) applies.

read_attributes

String

N/A

String that controls which properties are included in the
response document. The configuration value must be specified
using property
selection syntax.

resource_id

String

mandatory=true, nullable=false

OCAPI resource identifier. For example:
/products/*/images or
/products/specific_id/images. This
property supports Ant path style to describe resource IDs. You
can specify wildcards or specific product IDs; you can also
specify the pattern /products/** to access to
all available subresources. You can list all resource
identifiers for the Shop API, version 19.1, with the following
meta data call:
http://{your-domain}/dw/meta/rest/shop/v19_1?client_id={your-client-id}

Array of VersionRange documents granting permissions only
to a subset of OCAPI versions.

write_attributes

String

N/A

String that controls which properties can be included in
the request document. The configuration value must be specified
using property
selection syntax.

VersionRange Document

Use this
document to grant resource permissions only to a subset of Open Commerce
API versions. You can use the properties from and
until to define the range. At least one must be
specified.

Property

Type

Constraints

Description

from

String

N/A

From version (for example, 19.1). If you don't
specify the from version, all versions earlier
than the until version are accessible.

until

String

N/A

Until version (for example, 19.1). The
until version is not included in the range.
(For example, if the until version is 19.1,
then 18.7 is the latest included version.) If you don't specify
the until version, then all versions, including
the most recent one, are accessible.

Expansions

Resources that
support expansion technique are handled as any other resource. Therefore,
if you want to restrict access to product image information, configure
independent client permissions for each resource: the products base
resource /products/*, and the images subresource
/products/*/images.

Customization

The Open
Commerce API enables you to customize how some data is returned. You can
set properties for the following resources:

/product_search/images (Shop API)

/products/*/availability (Shop API)

/products/*/prices (Shop API)

/search_suggestion (Shop API)

/product_search/images (Shop
API)

You can customize how image information is returned by
configuring the image view types for certain image properties. There are
three reserved key/value pairs for this resource:

Those properties define the actual image view types. Based on the
view type, the Shop API returns the desired image information. If the
view_type is not set or if the view_type is unknown, the image properties
are not part of the response. For example:

You can configure max thresholds (returned by the Shop API) to
hide real ATS and stock levels. There are two reserved key/value pairs for
this resource:

"product.inventory.ats.max_threshold":"100"

"product.inventory.stock_level.max_threshold":"50"

ATS and stock levels are sensitive information for
merchants. If these properties are not set, the API response properties
have the default value 999999.

/products/*/prices (Shop
API)

You can configure which price book prices are exposed in the
product.prices property. There is one reserved key/value
pair for this resource:

"product.prices.price_book_ids":"usd-list-prices,usd-sale-prices"

If no price book is defined, the property is not part of the
response.

/search_suggestion (Shop
API)

You can customize how image information is returned by
configuring the image view types for certain image properties. There are
three reserved key/value pairs for this resource:

"suggestion.product.image:view_type":"small"

Those properties define the actual image view types. Based on the
view type, the Shop API returns the desired image information. If the
view_type is not set or if the view_type is unknown, the image properties
are not part of the response. For example: