Upgrade considerations for Product API v2

5 min

This topic describes upgrade considerations of Product API v2.

As part of moving to v5 of Optimizely Configured Commerce, we are rethinking the Catalog API, which includes several calls and options. The goal is to create a more responsive API that only returns the data that is really needed and provides options from an API’s perspective, not from our specific implementation perspective.

During the review, it was determined that Insite.Catalog will have the v2 of the Product API added. CatalogPages will no longer be used in v5 CMS and the Warehouses. Category APIs will remain the same. With the exception of the Product API, which will have both v1 and v2 versions, everything else within the Catalog module will remain as v1 implementations.

You can use the Product API v2 with both Classic and Spire CMS options, but if you are moving from Product API v1 to Product API v2, you will need to redo any customizations you've made.

General Notes

All primary product queries now start with an Elasticsearch call. We are populating enough additional information in the index to ensure that the product list page, under many situations, can be populated entirely from Elasticsearch. This will remove additional calls back to Elasticsearch to validate for restrictions.

CatalogPages has been replaced by CMS API calls.

The “Only Facets” expand option has been removed from Products - it will now need to be handled in the front-end UI.

All calls to the Products API should be returning only products.

We do not return data that is not from the context of the API itself (i.e. Product API will no longer have “QtyOrdered” on it or pricing or inventory in general).

Fields were renamed to conform to how they are referred to in the Admin Console (i.e. Styled = Variant; erpNumber = productNumber, shortDescription = productTitle).

Like items are grouped together on the payload to make it easier to see and find related data.

All product calls should be paged.

Considerations

While the data returned in the API will be very similar to the v1 version, it will not be identical. Implementing the v2/Products API will require some work. Below are some of the things to watch out for and consider:

Make sure to remap the names of the fields to match the glossary changes mentioned later in this document.

Since we are pulling more data back from Elasticsearch on the initial call, data that is on the base Product record will need to be retrieved with an expands to Detail, which is new.

Units of Measure will always be returned with the Product as a collection and the base U/M will be the (0) element and marked as the default if no other ProductUnitOfMeasure record is marked as the default.

If the customer sets up the Base U/M on the product record and also sets it up as an alternate unit of measure, both will be presented in the returned data so you may need to code around that for display.

Inventory and pricing are no longer returned with the Products API – separate call(s) will need to be made to retrieve that data. The singular exception is the expand=Warehouses which will return inventory if it is NOT real-time inventory. Additionally, all pricing and inventory should go through the RealTime APIs even if they are retrieving their data directly from the database.

TopSellersMaxResults and alsoPurchasedMaxResults can be replaced with a pageSize parameter.

ReplaceProducts parameter – the v5 design will show the replacement product with a link – it will no longer quietly replace it. QuickOrder will automatically replace the product without specifying a parameter. When sending in the ExtendedNames parameter, it resolves to a specific product and that product has both no inventory and a replacement product assigned, it will replace the product. This behavior is that same as in v1 of the API and expresses itself inside the QuickOrder process.

API Endpoints

In general, the data returned from the API will depend on both the specific endpoint selected and the various query string parameters added.

The general form of the calls will be:

api/v2/products?search=<search criteria>&select=<fields to return>&expand=<option list>&<parameter=value>&<parameter=value>\

Some parameters will not require any value to be provided, but most will require a value and they will need to be in the format <parameter>=<value>. The default values, if defined, will be applied automatically and do not need to be added to the query unless the opposite of the default is required.

If a parameter indicates it is a “list” of entries, the expectation is to repeat the entry for each one. An example would be ProductIds=<productid>&productIds=<productid>.

Endpoint	Purpose and Usage
api/v2/products	Returns a collection of products based on filtering criteria. Data returned will depend on the additional parameters sent. Referred to as the collection endpoint.
api/v2/products/{productid}	Returns a single product along with additional information based on parameters sent. Referred to as the single product endpoint.
api/v2/products/{productid}/other...	Refers to the format for additional, specific endpoints.