Shopper API Performance and Best Practices

Optimize your shopper experience and B2C Commerce instance operations using the following Shopper API performance best practices. The choices you make in API implementation, testing, and monitoring all significantly influence storefront performance.

The best practices provided in this article focus on Shopper API performance. Some of this information also applies to Admin APIs, but some of it does not, for example: the hook-related information.

When you build a feature, you must decide which APIs you will use to build it:

• Shopper APIs (out-of-the-box)
• Shopper APIs with hooks
• Custom APIs

This decision impacts performance and the amount of performance-related work that you must do. SCAPI performance is a shared responsibility, which is summarized in the following table:

Use the out-of-the-box (OOTB) Shopper APIs when the provided functionality is sufficient.

For example, let's say you're building a storefront and you want to display a list of products. You can typically accomplish this with existing Shopper Search or Shopper Products API functionality.

When you call Shopper APIs, pay attention to:

The larger your catalog, the longer certain platform requests take, for example: if you search using Shopper Products, searching a small number of products is faster than searching a large number of products.

Make sure you understand your catalog data and test for worst-case scenarios. Some Shopper APIs return responses that aren't paginated, such as categories and variants, which can result in very large response sizes.

For example: you call getCategories with levels=2 and id=root. If your category tree includes thousands of categories, the resulting response is large. Or, you call getProducts with expand=variants for a pair of paints that can vary by fit, waist, inseam, colors, washes, rise, and stretch. This could easily produce a huge response!

Bigger responses take longer to retrieve and transfer.

Response size is impacted by:

• Your catalog and number of objects
• Expansions
  • Many Shopper APIs support expansions, which is the ability to query related objects. Expansions also increase retrieval and transfer time.
• Custom attributes
  • Use custom attributes to extend system objects. Use select or hooks to remove attributes you don't need.

Use the select or expand parameters to only select the response properties you need. For complex response filtering, use modify hooks.

Ensure your API client is configured to request compressed resources.

Expansions impact cache effectiveness as some expansions can only be cached for a short amount of time. If you must use an expansion with low cache time, like availability, which can only be cached for 60 seconds, consider making an additional request to retrieve it when needed. This is especially important for API endpoints you call frequently, like product search and get products. For details, see Default Cache Expiration and Personalization Settings.

Be careful about adding intermediate caches on top of B2C Commerce APIs. Most API responses can be personalized, which means it isn't possible to use only the URL as the cache key in an upstream caching system like NGINX or a stacked CDN.

If a Shopper API exists, but it doesn't have all the data or functionality you need, you can extend it using hooks.

APIs that include hooks are always slower than APIs without hooks, because there is additional code to execute. With hooks, the Shopper APIs and your hook customizations are being run. If you're adding hooks, you are responsible for the performance of your code, so make sure you perform adequate performance testing to ensure that code you're using is performant.

Hooks are extensions to system logic, and these extensions run whenever the applicable API logic is run. For example, Shopper API code runs frequently, so make sure you:

• Follow the best practices previously listed in Shopper API Implementation Best Practices.
• Use the code profiler to view the performance of your hooks.
• Consider whether your hook logic impacts how long a response can be cached. Modify the out of the box caching if required using the Script API.
• Minimize calls to external systems. If you must call out to an external service, use the service framework and ensure the associated service's profile has aggressive timeout and circuit breaking settings. Review whether it is possible to import the external data into your B2C instance rather than requesting it at runtime.
• Consider caching expensive operations in a custom caches. Custom caches are limited to 20B total and 128KB per entry. If these limits are exceeded, a warning is returned. For custom cache details, see Custom Caches.

Use Custom APIs when no equivalent Shopper API exists for what you want to do. This involves code that you write, so make sure you perform adequate performance testing for your Custom APIs.

• Follow the best practices previously listed in Shopper API Implementation Best Practices and Hook Implementation Best Practices.
• With custom APIs, you are responsible for caching. Consider whether responses from your API are suitable for caching, and if so, use the Script API to ensure that the platform caches them.
• Use remote includes where applicable to create reusable response fragments that you can cache separately, such as promotion details or product information.

Measure the speed of your endpoints, hooks, and Custom APIs. Slow responses impact shopper experience and also make your storefront instance work harder. Your storefront can serve far more fast responses than slow responses.

• For SCAPI response time constraints, see Error Codes.
• For help resolving request timeouts, See Troubleshoot Request Timeouts.

Check your API performance with your initial implementation, but also implement continuous monitoring after building them, as performance is an ongoing concern. Two key performance testing approaches are laboratory testing and field testing.

Laboratory testing involves setting up ongoing performance tests against specific endpoints and measuring the results. If performance drops, an alarm (such as an email) alerts your team to review it. This is typically done in Continuous Integration environments.

Field testing measures the performance of actual API calls in real-world usage. For details, see Reports and Dashboards Technical Timing SCAPI page.

Laboratory testing uses controlled conditions to test out API changes, for example, testing it in rapid succession to ensure that you haven't regressed performance and that performance meets acceptable standards before deployment.

You can integrate laboratory testing into your continuous integration (CI) to create tests that record timing information, for example: create a test that makes multiple requests to your APIs.

If performance is too slow:

• See collect request details for how to inspect and track Shopper API, hook, and Custom API call times.
• Use the code profiler to investigate timing bottlenecks in your code.

Field testing measures performance in a live environment after deployment, for example: measuring how long requests take from different shoppers. This helps you understand what is happening with your API calls and check for edge cases or other unexpected issues that you missed in laboratory testing.

Use The Account Manager Technical Timing tab and SCAPI tab to view how your APIs and controllers are operating at scale. This information shows::

• Average response time over time, number of requests, and status codes

• Performance distribution:

  • Drill down to view the performance and behavior of specific APIs, including Custom APIs. For example, you can look at an API family, such as Shopper Baskets, and drill into endpoints within that API family. You can also view and drill into custom APIs, and sort by the most frequently called endpoints to see average response times.

• Trends:

  • Monitor trends over time and after important code changes. For example, you can overlay data with code changes to evaluate whether your code changes regressed performance.

Helpful questions to ask:

• Did response time increase because I made a code change?
• Did response time increase because people are searching for different things?

To understand and address timing bottlenecks, use the code profiler.