Migrating to version 3.0

Background

Version 3.0 of the SDK introduces the new Catalogue API v2. The v2 API is very similar to the v1 API, except that CID is required in many product API endpoints. The goal is to disambiguate catalogues which have same enterprise, catalogue id, version, vendor, and price list. This is useful when you want to have a test and production version of your portfolios. Usually the catalogues inside have the exact same enterprise, catalogue id, version, vendor, and price list - with the unique CID as the only differentiator. The v1 API does not allow you to do this because it is missing the CID information. Now with the V2 API, you can query these portfolios from Stage in deterministic way.

tip

The V1 API is still available to support older Stage SDK versions.

Breaking Changes

The addition of CID in the URL path creates a few breaking changes in the library interfaces. Essentially CID is no longer optional in all catalogue or product identifiers.

DtoCatalogueParams

The field cid is added as a required field in the DtoCatalogueParams interface. This affects other interfaces which extend it:

• DtoCatalogueParamsWithCid is redundant and has been superseded by DtoCatalogueParams.
• DtoCatalogueParamsWithCidAndLang is renamed to DtoCatalogueParamsWithLang.
• DtoProductParamsWithCid is renamed to DtoProductParams.
• DtoProductParamsWithCidAndLang is renamed to DtoProductParamsWithLang.

They also apply to both requests and responses objects of the Catalogue API. For example, the DtoAdditionalProductRef.catId in the API response always contains the cid field now.

The change affects several functions' signatures in the SDK. If you are calling any of the following SDK functions in your code, you will need to update them to pass along CID in their arguments. For example:

    key={makeCatalogueKey({
+       cid,
        enterprise,
        prdCat,
        prdCatVersion,
        vendor,
        priceList
    })}

Package @configura/web-api

• applyCatalogueFilters
• correctDefaultsOnCatalogueParams
• decodeCatalogueParams
• decodeProductParams
• fillMissingPrdCatVersionFromPermissions
• generateProductConfigurations
• getPrdCatVersionOrLatestFromPermissions
• isSameCatalogueParams
• makeCatalogueKey
• makeProductKey

Package @configura/web-ui

• useMemoCatalogueParams
• useMemoProductParams

Non-Breaking Changes

The interface rename also changes the signatures of several functions in the SDK. However in practice this does not make a big difference because the interfaces already require CID previously.

For example, CfgProdut.make is updated in this release, but the call site should remain unchanged:

// Usage does not change
let product = await CfgProduct.make(api, {
    cid,
    enterprise,
    prdCat,
    prdCatVersion,
    vendor,
    priceList,
    lang,
});

Package @configura/web-api

• createCataloguePermissionsFilter
• wrapWithCache
• wrapWithGetProductCache
• wrapWithPostValidateCache
• CfgProduct.make
• CfgReferencePathHelper.getCataloguePath
• CfgReferencePathHelper.getProductPath