Update commerce extensions guide (#277)

Author: rahinisrinivas

Diff for: changelog/2024/2024-09-16-changelog.md

@@ -0,0 +1,8 @@
+---
+title: 'Added case-insensitive string uniqueness in Commerce Extensions'
+date: '2024-09-16'
+tags: ['Commerce Extensions']
+hide_blog_post_date: false
+---
+
+**MINOR** Previously, we had introduced the ability to model data with uniqueness constraints for string fields in Commerce Extensions. This feature is now further enhanced to be case-insensitive, that is, to take different cases into account for conflicts. For more information, see [Custom Fields](/docs/api/commerce-extensions/custom-fields#string-validation).

Diff for: guides/How-To/commerce-extensions/create-a-multilocation-inventories-resource.md

@@ -6,6 +6,11 @@ nav_position: 3
 
 Imagine managing inventory across multiple locations effortlessly. Commerce Extensions makes this possible with Custom APIs designed to handle specific data points like SKU, Collection Name, Location Name, and Inventory amount. This functionality allows businesses to quickly provide inventory information to customers, enhancing the shopping experience.
 
+In this guide you will learn how to:
+
+* Create a Custom API to store your location inventory data.
+* Ensure the accuracy of your inventory amounts using Conditional Updates to prevent lost updates and other data conistency issues.
+
 ## Prerequisites
 
 If you want to follow along, you need a [Client credential token](/docs/authentication/Tokens/client-credential-token).
@@ -38,25 +43,48 @@ Make sure to take note of the Custom API ID [returned](/docs/api/commerce-extens
 
 ## Create Custom Fields
 
-### Create Custom Field - slug
-In this step, you will create a Custom Field `slug`, this stores a string to represent this SKU.
+### Create Custom Field - sku
+
+In this step, you will create a Custom Field `sku`, this stores a string to represent this SKU.
 
 ```sh
 curl -X POST "https://useast.api.elasticpath.com/v2/settings/extensions/custom-apis/:customApiId/fields" \
      -H "Authorization: XXXX" \
      -H "Content-Type: application/json" \
      -d $ {
       "data": {
-        "slug": "slug",
+        "slug": "sku",
         "name": "Slug",
         "description": "Slug of the entry",
         "field_type": "string",
+        "validation": {
+          "string": {
+            "min_length": 12,
+            "allow_null_values": false,
+            "unique": "yes",
+            "unique_case_insensitivity": true
+          }
+        },
+        "use_as_url_slug": true
         "type": "custom_field"
       }
     }
 ```
 
+Some things to note about `validation` object in the sample request above:
+* `min_length`: Ensures that `slug` values have at least 12 characters.
+* `allow_null_values`: Will reject any `null` values from being stored as a `sku`.
+* `unique`: Blocks any duplicate values from being stored as a `sku`.
+* `unique_case_insensitivity`: Controls whether values with different cases (for example, `ABC` and `abc`) should conflict. Only applies when `unique` is set to `yes`.
+
+Each of these can be tailored to fit your business see [Custom Fields Overview](/docs/api/commerce-extensions/custom-fields) for more.
+
+Notice that the attribute `use_as_url_slug` is enabled, this will allow access to your data using well-known identifiers in your domain rather than having to rely on identifiers generated from our platform, we will build on this later. For a field to be configured for `use_as_url_slug`:
+1. `allow_null_values` must be set to `false`.
+2. `unique` must be set to `yes`.
+
 ### Create Custom Field - amount
+
 In this step, you will create a Custom Field `amount`, this stores the amount of inventory of this SKU at this location as an integer.
 
 ```sh
@@ -78,9 +106,10 @@ curl -X POST "https://useast.api.elasticpath.com/v2/settings/extensions/custom-a
       }
     }
 ```
-Take note of `validation` in the step above, this field is restricted to not allow negative values. For more information, see [integer validation](/docs/api/commerce-extensions/custom-fields#integer-validation).
+Take note of `min_value` in the step above, this field is restricted to not allow negative values. For more information, see [integer validation](/docs/api/commerce-extensions/custom-fields#integer-validation).
 
 ### Create Custom Field - location-name
+
 In this step, you will create a Custom Field `location-name`, this stores a string to represent where a SKU is stored. Additionally, you will restrict this value to specific options using regex.
 
 ```sh
@@ -102,31 +131,14 @@ curl -X POST "https://useast.api.elasticpath.com/v2/settings/extensions/custom-a
       }
     }
 ```
-Take note of `validation` in the step above, this field is restricted to only allow the following values:
+
+Take note of `data.validation.string` in the step above, this field is restricted to only allow the following values:
 * Paris
 * London
 * New York
 
 For more information, see [string validation](/docs/api/commerce-extensions/custom-fields#string-validation).
 
-### Create Custom Field - collection-name
-In this step, you will create a Custom Field `collection-name`, this stores a string to represent the collection a SKU is associated with.
-
-```sh
-curl -X POST "https://useast.api.elasticpath.com/v2/settings/extensions/custom-apis/:customApiId/fields" \
-     -H "Authorization: XXXX" \
-     -H "Content-Type: application/json" \
-     -d $ {
-      "data": {
-        "slug": "collection-name",
-        "name": "Collection Name",
-        "description": "Name of the collection",
-        "field_type": "string",
-        "type": "custom_field"
-      }
-    }
-```
-
 ## Create Custom API Entries 
 
 With your Custom API configured, create Custom API Entries to store you location inventories.
@@ -138,36 +150,43 @@ curl -X POST "https://useast.api.elasticpath.com/v2/extensions/location-inventor
      -d ${
       "data": {
         "type": "location_inventory_ext",
-        "slug": "LR-SFA-201",
-        "amount": 4,
+        "sku": "TBL-DIN-6WD-OAK-0034",
+        "amount": 40,
         "location-name": "Paris"
       }
     }
 ```
 
-Notice that the URL you made this request is slightly different, you were able to create a Custom API Entry against the `slug` of the Custom API you created earlier.
+Notice the following:
+* the URL you made this request is slightly different, you were able to create a Custom API Entry against the `slug` of the Custom API you created earlier.
+* the `type` in the request body was the `api_type` of the Custom API you created earlier.
+* the keys (`slug`, `amount` and `location-name`) of the attributes used in the request body are the `slug` of the Custom Fields you created earlier.
 
-In addition, the `type` in the request body was the `api_type` of the Custom API you created earlier.
+## Update Custom API Entries
 
-Finally, take note that the keys (`slug`, `amount` and `location-name`) of the attributes used in the request body are the `slug` of the Custom Fields you created earlier.
+Recall that [earlier](/guides/How-To/commerce-extensions/create-a-multilocation-inventories-resource#create-custom-field---sku) when you created the Custom Field `sku` that you marked it for `use_as_url_slug`. This allows you to access a Custom API Entry by the value that is stored in that Custom Field for that record rather than having to:
 
-## Update Custom API Entries
+1. Filter for that record.
+2. Save the `data.id` attribute for that record.
+3. Update that record using an auto-generated identifier.
 
-With your Custom API Entry created, you can update it to modify inventory `amount`.
+Given a Custom API Entry exists with `"sku": "TBL-DIN-6WD-OAK-0034"`, when you want to update the inventory `amount` you make the following request:
 
 ```sh
-curl -X PUT "https://useast.api.elasticpath.com/v2/extensions/location-inventories/:customApiEntryId" \
+curl -X PUT "https://useast.api.elasticpath.com/v2/extensions/location-inventories/TBL-DIN-6WD-OAK-0034" \
      -H "Authorization: XXXX" \
      -H "Content-Type: application/json" \
      -d ${
       "data": {
         "type": "location_inventory_ext",
-        "amount": 3
+        "amount": 43
       }
     }
 ```
 
-### Conditional Updates
+Notice that the resource identifier in the request above is one that should be well-known to you and your processes and not a random UUID generated by the platform `/v2/extensions/location-inventories/:customApiEntryId`. [Earlier](/guides/How-To/commerce-extensions/create-a-multilocation-inventories-resource#create-custom-field---sku) you made `sku` unique and case-insensive, so requests using a value like `tbl-din-6Wd-oak-0034` and similar varations using different casing will update, retrieve and potentially delete the same resource.
+
+## Conditional Updates
 
 When using Custom API Entries, if multiple independent clients update the same resource, you should have them use the `If-Match` header to prevent lost updates and other data consistency issues in the inventory amounts. For example, if two users simultaneously see an amount of 3 and each allocate 1, both would update the amount to 2. The `If-Match` header ensures that only one of these requests succeeds. It works by comparing the provided ETag value with the current ETag value of the resource. If the resource hasn't changed since you last read it, the ETag will not change, ensuring the update is safe.