#From product identifier to product UUID

#What will happen?

We deployed 8 new API endpoints, endpoints that have the same role as already-existing ones:

• GET /api/rest/v1/products-uuid, same as GET /api/rest/v1/products
• POST /api/rest/v1/products-uuid, same as GET /api/rest/v1/products
• PATCH /api/rest/v1/products-uuid, same as PATCH /api/rest/v1/products
• GET /api/rest/v1/products-uuid/{uuid}, same as GET /api/rest/v1/products/{code}
• PATCH /api/rest/v1/products-uuid/{uuid}, same as PATCH /api/rest/v1/products/{code}
• DELETE /api/rest/v1/products-uuid/{uuid}, same as DELETE /api/rest/v1/products/{code}
• POST a proposal /api/rest/v1/products-uuid/{uuid}/proposal (EE only), same as POST /api/rest/v1/products/{code}/proposal
• GET a draft /api/rest/v1/products-uuid/{uuid}/draft (EE only), same as GET /api/rest/v1/products/{code}/draft

From November 2022, the product identifier value (pim_catalog_identifier attribute) has now become optional.

#Why do we do that?

A PIM used to contain one and only identification: the so-called field identifier (the only pim_catalog_identifier attribute of the whole product). In Serenity, this field value is the main identifier of the product. You can now change your main identifier and choose another identifier attribute instead of the SKU. But what if the main identifier for your catalog changes overtime? What if you would like to transition from the SKU to an EAN as the main identifier for example? The identifiers on your products would then change and this why we recommend using our UUID API endpoints. The product UUID (for Universally Unique Identifier) allows every product on the PIM to have a unique and immutable way to identify it.

That's the purpose of the brand-new product UUID feature.

But before making it happen, a product must have a unique and immutable way to identify it: that's why we introduced the product UUID (for Universally Unique Identifier).

#What are the impacts?

Of course, Products endpoints will remain available (and they be enriched with a UUID property), even whith the availability of the new API endpoints. Nevertheless, now that the current product identifier is optional:

• GET /api/rest/v1/products won’t return products with empty product identifiers (in other words, you may miss products if you continue to use this endpoint);
• associations property for GET /api/rest/v1/products or GET /api/rest/v1/products/{code} may contain NULL values (product associated with a product without identifier);
• GET /api/rest/v1/products/{code} could result in a 404 error (if the identifier is removed from the product). ...and you could encounter some issues with your code.

#What do we advise you?

As UUID API endpoints have now been released, we recommend you to jump on the bandwagon right away:

• Change product-identifier-based products endpoints with UUID ones.
• Every time you identify a product with its identifier in your application, be sure to replace it by corresponding product UUID. You will easily find the match between product identifier and UUID in both products endpoints and new ones.

#An example of what you may have to do?

Let's imagine you developed a product-identifier-based solution that synchronizes PIM products to a random eCommerce solution.

You persist the correlation between PIM products and eCommerce ones in a correlation table.

    TABLE correlation {
          akeneo_identifier,
          ecommerce_identifier
      }
    

Today, its running is as follows:

  Get all Akeneo products with GET /api/rest/v1/products
      For each retrieved products:
        identifier = identifier of the product
        Get the ecommerce_identifier matching identifier by querying the correlation table
        if ecommerce_identifier was not found
          Add the product to the eCommerce
          Add (identifier, ecommerce_identifier) in the correlation table
        else
          Update the product identified by ecommerce_identifier in the eCommerce
    

How do you turn your application into a product-UUID one?

Firstly, replace the way of getting Akeneo products: from GET /api/rest/v1/products to GET /api/rest/v1/products-uuid. Then, add a UUID column to your correlation table.

    TABLE correlation {
          akeneo_identifier,
          akeneo_uuid,
          ecommerce_identifier
      }
    

And at last, step by step, replace akeneo_identifier in your correlation table with uuid

    Get all Akeneo products with GET /api/rest/v1/products-uuid
        For each retrieved products:
            identifier = identifier of the product
            uuid = uuid of the product
            Get the ecommerce_identifier matching uuid in the correlation table
            if ecommerce_identifier was not found
                Get the ecommerce_identifier matching identifier in the correlation table
                if ecommerce_identifier was found
                    Add uuid in the correlation table
                    Update the product in the eCommerce
                else
                    Add the product to the eCommerce
                    Add (identifier, uuid, ecommerce_identifier) in the correlation table
            else
                Update the product identified by ecommerce_identifier in the eCommerce