update commerce extensions (#283)

Author: rahinisrinivas

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

@@ -0,0 +1,8 @@
+---
+title: 'Added configuration of immutable Custom Fields in Commerce Extensions'
+date: '2024-09-18'
+tags: ['Commerce Extensions']
+hide_blog_post_date: false
+---
+
+**MINOR** We have introduced the ability to configure a Custom Field  as `immutable`, allowing you to better align your Custom API with your business needs. When set to true, the value of this field can be specified only during POST requests and cannot be modified during PUT requests. For more information, see [Custom Fields](/docs/api/commerce-extensions/custom-fields#immutable).

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

@@ -9,6 +9,7 @@ Imagine managing inventory across multiple locations effortlessly. Commerce Exte
 In this guide you will learn how to:
 
 * Create a Custom API to store your location inventory data.
+* Streamline your data import and sync processes using upserts and accessing entries with well-known identifiers.
 * Ensure the accuracy of your inventory amounts using Conditional Updates to prevent lost updates and other data conistency issues.
 
 ## Prerequisites
@@ -34,12 +35,13 @@ curl -X POST "https://useast.api.elasticpath.com/v2/settings/extensions/custom-a
         "api_type": "location-inventories_ext",
         "name": "Location Inventories",
         "description": "Inventory entries for all SKUs at all retail locations.",
+        "allow_upserts": true,
         "type": "custom_api"
       }
     }
 ```
 
-Make sure to take note of the Custom API ID [returned](/docs/api/commerce-extensions/create-a-custom-api#responses), you must replace `:customApiId` in the following step with the Custom API ID.
+Make sure to take note of the Custom API ID [returned](/docs/api/commerce-extensions/create-a-custom-api#responses), you must replace `:customApiId` in the following step with the Custom API ID. Additionally, ensure that `data.allow_upserts` is set to `true`, this allows to perform [upserts](/guides/How-To/commerce-extensions/create-a-multilocation-inventories-resource#update-custom-api-entries) for Custom API Entries.
 
 ## Create Custom Fields
 
@@ -167,7 +169,7 @@ Notice the following:
 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:
 
 1. Filter for that record.
-2. Save the `data.id` attribute for that record.
+2. Save the `id` attribute for that record.
 3. Update that record using an auto-generated identifier.
 
 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:
@@ -186,6 +188,24 @@ curl -X PUT "https://useast.api.elasticpath.com/v2/extensions/location-inventori
 
 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.
 
+## Upsert Custom API Entries
+
+To further simplify and optimize your data import and synchronization processes, you can upsert Custom API Entries. Instead of first checking whether a record exists before deciding to create or update a Custom API Entries, you can upsert a record. If the record exists, it is updated; if it doesn't, it is inserted or created. This is enabled by setting `allow_upserts` when you [created this Custom API](/guides/How-To/commerce-extensions/create-a-multilocation-inventories-resource#create-a-new-custom-api---location-inventories).
+
+```sh
+curl -X PUT "https://useast.api.elasticpath.com/v2/extensions/location-inventories/FURN-SOFA-3S-LTH-BLK-0021" \
+     -H "Authorization: XXXX" \
+     -H "Content-Type: application/json" \
+     -d ${
+      "data": {
+        "sku": "FURN-SOFA-3S-LTH-BLK-0021",
+        "type": "location_inventory_ext",
+        "amount": 12,
+        "location-name": "Paris"
+      }
+    }
+```
+
 ## 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. 

Diff for: openapispecs/commerceextensions/OpenAPISpec.yaml

@@ -63,10 +63,11 @@ tags:
       | Validation: Allow null values     | ⛔                | ✅                                          |
       | Validation: Unique(String)        | ⛔                | ✅                                          |
       | Validation: Unique Case Insensitivity(String)        | ⛔                | ✅                                          |
+      | Validation: Immutable             | ⛔                | ✅                                          |
 
       ## Validation
 
-      When [creating](/docs/api/commerce-extensions/create-a-custom-field#request) or [updating](/docs/api/commerce-extensions/create-a-custom-field#request) a Custom Field, `validation` can be used to limit the values that may be stored in the corresponding Custom API Entry.
+      When [creating](/docs/api/commerce-extensions/create-a-custom-field#request) or [updating](/docs/api/commerce-extensions/update-a-custom-field#request) a Custom Field, `validation` can be used to limit the values that may be stored in the corresponding Custom API Entry.
 
       :::note
 
@@ -152,7 +153,27 @@ tags:
           }
         }
       }
-        ```
+      ```
+
+      ### Immutable
+
+      When [creating](/docs/api/commerce-extensions/create-a-custom-field#request) a Custom Field, it can be configured to be `immutable`. When set to true, the value of this field can be specified only during POST requests and cannot be modified during PUT requests. By default, this is `false`.
+
+      sample validation object :
+        
+      ```json
+      {
+        "validation": {
+          "boolean": {
+            "immutable": false
+          }
+        }
+      }
+      ```
+
+      ## Presentation
+
+      When [creating](/docs/api/commerce-extensions/create-a-custom-field#request) or [updating](/docs/api/commerce-extensions/update-a-custom-field#request) a Custom Field, `presentation` can be used to influence the layout of fields within a Custom API in User Interface. It does not order or affect the JSON response, and has no semantics on the backend.
       
       ## Reserved Slugs
 
@@ -1448,6 +1469,53 @@ paths:
                         }
                       }
                     }
+        '201':
+          description: Created
+          headers:
+            ETag:
+              description: "A unique identifier representing the current version of the resource. When the resource changes, the ETag value will also change. The ETag hash will be the same value as `etag_id`, and is marked as a weak entity tag string. For example: etag: W/\"5feceb66ffc86f38d952786c6d696c79c2dbc239dd4e91b46729d73a27fb57e9\", etag_id: 5feceb66ffc86f38d952786c6d696c79c2dbc239dd4e91b46729d73a27fb57e9"
+              schema:
+                type: string
+          content:
+            application/json:
+              schema:
+                required:
+                  - data
+                properties:
+                  data:
+                    type: object
+                    additionalProperties: true
+                    required:
+                      - id
+                      - type
+                      - values
+                    $ref: "#/components/schemas/CustomApiEntryAttributes"
+              examples:
+                valid_entry:
+                  summary: "Default Wishlist"
+                  # language=JSON
+                  value: |
+                    {
+                      "data": {
+                        "id": "7e067539-6f6c-46e1-8c55-940031b36c6a",
+                        "type": "wishlist_ext",
+                        "name": "My Wishlist",
+                        "items_count": 0,
+                        "keep_purchased": false,
+                        "links": {
+                          "self": "/extensions/wishlists/7e067539-6f6c-46e1-8c55-940031b36c6a"
+                        },
+                        "meta": {
+                          "timestamps": {
+                            "updated_at": "2017-01-10T11:41:19.244Z",
+                            "created_at": "2017-01-10T11:41:19.244Z"
+                          },
+                          "resource_version": 0,
+                          "data_size": 6,
+                          "etag_id": "5feceb66ffc86f38d952786c6d696c79c2dbc239dd4e91b46729d73a27fb57e9"
+                        }
+                      }
+                    }
         '400':
           $ref: '#/components/responses/ValidationError'
         '404':
@@ -1795,6 +1863,10 @@ components:
           description: Specifies a unique API type for this Custom API. Entries for this API will use this value for their `type` field. This field must be suffixed with `_ext` to distinguish it from built in APIs.
           examples:
             - "wishlist_ext"
+        allow_upserts:
+          type: boolean
+          description: Controls whether upsert operations are allowed for Custom API Entries via the `PUT` method. When set to `true`, it allows the creation of new Custom API Entries using `PUT` if the record doesn't exist, and updates the existing record if it does. When `false`, `PUT` requests can only update existing entries.
+          default: false
         links:
           readOnly: true
           $ref: '#/components/schemas/SelfLinkCustomApi'
@@ -1849,6 +1921,20 @@ components:
             - "integer"
             - "boolean"
             - "float"
+        use_as_url_slug:
+          type: boolean
+          description: |
+            Enabling this field will mean Custom API Entries created in this Custom API will use this value in the URL instead of the `id` attribute. In order to set this field, the field must be a string, and unique, not allow null values, no entries have been created yet, and this field cannot be set to true on another custom field. This field cannot be updated. In addition to any validation rules you create, the values must be [Unreserved URL Characters](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3) (i.e., be alpha-numeric, or one of `-`, `.`, `_` or `~`).
+        presentation:
+          type: object
+          properties:
+            sort_order:
+              type: integer
+              description: Specifies the order of the field in the User Interface.
+              example: 10
+              default: 0
+              minimum: 0
+              maximum: 1000
         links:
           readOnly: true
           $ref: '#/components/schemas/SelfLink'