OCAPI Best Practices 23.2

These tips help you develop scalable, high-performance OCAPI applications.

Choosing OCAPI Instead of Controllers or Pipelines

OCAPI requests and storefront requests (Controllers or Pipelines) have different resource costs and platform overhead. The information here can help you make the right choice for your application.

What are the key differences?

OCAPI requests have their own application tier cache. It follows similar clearing behavior to that of the web tier cache, but the web tier does not cache OCAPI requests.
Because the web tier doesn’t cache OCAPI requests, they always incur the same application-tier overhead as uncached storefront requests, regardless of cache status. Therefore, OCAPI requests have a higher resource cost than storefront requests that are cached by the web tier.
An OCAPI request that retrieves multiple response documents applies the minimum cache TTL among those documents to all of them. A storefront request, on the other hand, respects the individual cache TTLs of each element of remote-include content.

What is the effect on thread behavior?

Thread behavior is the same for OCAPI and storefront requests: each request generates a new thread to handle the response. The appropriate request payload size can vary, based on the situation.

Remember that a long-running request keeps a thread occupied.
To determine the appropriate balance between payload size and request time, monitor your application’s performance and tune it as needed. This balance is specific to each application. For example, one case calls for a single request that returns 50 responses, while ten requests returning five responses each offer better performance for another case.
Use batch requests appropriately.

How does poor OCAPI performance affect the customer experience?

OCAPI requests, storefront requests, and scheduled jobs all share the platform resource pool. Therefore, poor performance in one area not only adds its own wait time to the customer experience, but also affects performance in other areas.

OCAPI Cache Management

Here we expand on the many considerations related to caching OCAPI requests.

What types of OCAPI requests can be cached?

Data API: No
Note: Each Data API request incurs real-time application-tier overhead. Try to minimize the number of Data API calls made by your application.
Meta API: Yes
Shop API: Yes (most requests)

How are Meta API requests cached?

Meta API resources are always cached for one day. You can’t configure their TTL. To clear the Meta API instance cache, invalidate the entire Business Manager page cache. (Invalidating only a cache partition does not clear the Meta API cache.)

Note: Clearing the page cache can create a heavy load on the application servers. Only clear the page cache manually when necessary, and avoid clearing it during times of high traffic.

How are Shop API requests cached?

You configure caching of individual Shop resources in the OCAPI Settings using two properties. Minimize cache misses by configuring appropriate TTLs and eliminate cache stores (duplicate cache content) with a good request URL strategy.

cache_time (Integer): Lifetime of the cached response document, in seconds. The default value is 60, and the valid range is from 0 through 86,400 (24 hours).
personalized_caching_enabled (Boolean): Specifies whether response documents are cached per customer context (JWT). The default value is true. Disabling personalized caching can improve performance, but can only be done if the response document is customer-agnostic and is not needed for any customer-specific processing.

How are cache keys generated for Shop API responses?

OCAPI cache keys are similar to storefront page cache keys. They are generated from the following request elements.

hostname
siteId
clientId
expansion parameters
custom request URL parameters

How does a request URL affect cache performance?

The structure of a request URL affects the generated cache key. Matching requests that include the same parameters, but combine them in a different order, generate multiple cache entries. For example, these three requests result in three different cache entries for the same response data:

dw/shop/v18_8/products/123?client_id=[your_own_client_id]&expand=availability,variations
dw/shop/v18_8/products/123?expand=availability,variations&client_id=[your_own_client_id]
dw/shop/v18_8/products/123?expand=variations,availability&client_id=[your_own_client_id]

Duplicate entries can significantly degrade cache performance. To prevent them, always build request URLs with the query parameters and parameter values in alphabetical order.

What types of OCAPI data exist in the cache?

OCAPI data is cached in two ways: individual document entries, and composite entries that combine multiple documents (an object document plus documents representing expansions included in the request).

Individual documents are stored in and retrieved from cache individually. For example, a request that returns multiple Product documents, with no expansions, checks the cache for individual matching Product documents.
Composite data that includes expansion documents is only retrieved from the cache if an entry exists that matches the requested combination of documents. (Remember that the cache key includes the requested expansions.) If no matching entry exists, then the requested documents are all retrieved from the database and stored together as a single combined cache entry. This cache entry is in turn only available to requests for the same combination of documents. For example, consider a request that returns a Product document, plus expansions for Inventory and Promotion documents. It only retrieves data from cache if it finds a combined entry that includes matching Product, Inventory, and Promotion documents. Because such an entry is only available to a matching request, a request for only the Product document with no expansions ignores it.
Note: When a composite entry is stored in cache, its TTL is equal to the shortest configured TTL of the included document types. This behavior differs from the behavior of storefront pipeline and page caching, where different elements of a page can be cached separately. For example, consider a Product document with a TTL of 86,400 seconds, and an Inventory document with a TTL of 300 seconds. A request for a Product document with the availability expansion (which returns an Inventory document) generates a cache entry with a TTL of 300 seconds. For this reason, use requests that group documents with similar cache times when possible. Also, when planning, be aware of requests that retrieve data from the database more frequently than expected for that data.

Are cache entries based on requests or responses?

Cache entries are based on responses, not requests. Therefore, every OCAPI request incurs the application-tier overhead to parse it and retrieve documents from the cache or database.

How does replication affect OCAPI caching?

Replication clears the entire OCAPI cache along with the site cache.

How can I clear the OCAPI cache?

To clear the OCAPI cache, invalidate the site page cache. Doing so invalidates both caches, which cannot be cleared separately. See Invalidate a Page Cache Partition.

Note: Clearing the page cache can create a heavy load on the application servers. Only clear the page cache manually when necessary, and avoid clearing it during times of high traffic.

Are there tools for monitoring OCAPI cache performance?

The platform does not provide direct visibility to the OCAPI cache. The Reports and Dashboards in Business Manager describe cache behavior only for storefront pipeline requests.

Improving OCAPI Request Performance Using Cache-Control Headers

Some Shop API GET and HEAD request responses include Cache-Control headers that reflect the configured cache times for the retrieved documents. You can use this header data to effectively cache the documents outside of the B2C Commerce platform by retaining data and timing your OCAPI requests accordingly. The max-age argument in the header specifies how long to use the returned document before retrieving it again.

How can I use the max-age argument in the Cache-Control header to cache OCAPI response data?

The max-age argument represents the remaining TTL of the data in the OCAPI cache. For example, consider a resource with a configured cache-time of 900 seconds.

A GET request is made for the resource and retrieves a document that is not yet in cache. The response header includes a max-age value of 900. The document is stored in cache.
Another GET request is made to retrieve the same document 120 seconds later. This response header includes a max-age value of 780. This value is calculated by subtracting the document’s current time in cache (120) from the configured resource cache time (900). Your application can use the data without retrieving the document again until its effective TTL of 780 seconds has elapsed.

Which Shop API resources include Cache-Control headers?

The following resources include Cache-Control headers in their GET and HEAD request responses.

Categories
Content
ContentSearch
CustomObjects
Folders
Products
ProductSearch
Promotions
SearchSuggestion
Site
Stores

Because they are tied to sensitive data (such as customer or order processing data), the following resources do not include Cache-Control headers.

Ai
Baskets
Customers
GiftCertificate
OrderSearch
Orders
PriceAdjustmentLimits
ProductLists
Sessions

Can I use an external Content Delivery Network (CDN) to improve OCAPI performance?

If you use an external CDN to manage content, you can configure it to broker OCAPI requests and manage external caching based on the Cache-Control headers.

You can treat some OCAPI responses as static content, and provide default minimum cache times.
Depending on the features of the CDN, you can create multiple cache partitions, and associate specific OCAPI requests with specific partitions. Then you can customize cache behavior for each partition to apply to its set of requests.
You can manage an external OCAPI cache separately from the storefront page cache, effectively decoupling them.

Can I use the embedded B2C Commerce CDN to improve OCAPI performance?

No. The embedded CDN doesn’t include a reverse proxy that can manage OCAPI requests.

Extending and Customizing OCAPI

Here are some general tips on maximizing OCAPI performance.

What are some good practices when using custom hooks?

Hooks introduce dependencies and extra request overhead. Use them only when the benefits outweigh these costs.
When modifying an OCAPI response, use the web object whenever possible. Use the Script API only when necessary, and keep the hook business logic simple.
Avoid requesting persistent objects within a hook (such as ProductMgr.getProduct() or product.getVariations()).

How do cache time configurations affect custom hooks?

Custom hook logic attached to an OCAPI resource only executes when the data is retrieved from the database. Retrieving documents from cache does not trigger a custom hook.

What should I know about creating custom API endpoints that leverage custom controllers?

Controllers are stateful. Every time you access a controller endpoint, you spawn a new request object and, potentially, a new session. To continue using a session, client applications must accept the cookie embedded in the initial response and include it in subsequent requests. Failing to do so creates and abandons a new session with every request. The resulting flood of orphaned sessions can severely impact performance.

Is there a preferred way to make OCAPI requests from different clients, such as browsers or mobile applications?

Retrieve the JSON Web Token (JWT) and use it to make requests. Using it conserves platform resources and provides other benefits.

You can reuse a session instead of creating a new one for each request.
It enables ORM caching for OCAPI requests.
It enables personalized caching.