REW-2794-Product-Variant-Verbiage

README.md

@@ -2,7 +2,7 @@
 
 ## Adding an end-point
 - create a file in `/includes/api/{module}`
-- use the structure, language and style from `/includes/example/_kittens.md` 
+- use the structure, language and style from `/includes/example/_kittens.md`
 - add the file to `includes:` section of `index.html.md` (alphabetically)
 
 Once the changes have been made, create a PR to master. When the PR is merged, GitHub Actions will pickup the changes and deploy.
@@ -24,15 +24,27 @@ Each section should contain the following elements in this order:
 
 - `> Header:`
 - `> Body:` (POST only)
-- `> Response:` 
+- `> Response:`
 - Description of the end point
 - H4 (####) HTTP Request
 - GET/POST/DELETE
-- H4 (####) Request Parameters 
+- H4 (####) Request Parameters
   - _if there are URL and Body params, then create two more sections:_
-  - H5 (#####) URL Parameters 
+  - H5 (#####) URL Parameters
   - H5 (#####) Body Parameters
 - H4 (####) Response Parameters
-
 
+## Testing Locally
 
+### Requirements
+- Git
+- Docker with compose
+
+### Steps
+1. Clone the repo.
+2. Run `docker compose build` at least once to build the images.
+3. Run `docker compose up` to start the slate instance container.
+4. Visit `http://localhost/` in your browser.
+5. Make changes to the markdown files in the `source` folder.
+6. Refresh the browser to see the changes.
+7. When done, run `docker compose down` to stop the container.

docker-compose.yml

@@ -1,19 +1,16 @@
----
-version: '3'
 services:
+
   slate:
     build:
-      context: .
+      context: ./
     volumes:
-      - .:/srv/slate
+      - ./:/srv/slate/
     ports:
-      - 4567:4567
-    command: sh -c '
-      bundle install &&
-      if [ "$BYEBUG" -eq "1" ];
-        then echo "sleeping";
-        sleep 100d;
-      else
-        bundle exec middleman server;
-      fi
-      '
+      - 80:4567
+    entrypoint: >-
+      /usr/bin/env bash -e -c
+    command:
+      - >-
+        bundle install &&
+        /srv/slate/slate.sh build &&
+        /srv/slate/slate.sh serve;

source/includes/api/products/create_product_v2.md

@@ -220,12 +220,12 @@ voucher  | Boolean  |  Required - indicates if this product is to be treated as
 lowest_denomination  | Integer  | Optional conditional - if this product is considered a voucher this field should indicate the lowest denomination of voucher available
 catalogue_id  | Integer  |  Optional - The id of the catalogue the product should belong to
 categories  | Array  |  Optional - An array of category ids that the product should belong to
-variants  | Array  |  Required - this is (somewhat convolutedly) a list of at 0 or more JSON encoded strings representing objects for a variant
+brand_id  | Integer  | Optional - this indicates a brand. Note this is not the name of the brand, but the id of the brand as stored in GPS
+variants  | Array[Strings]  |  Optional - an array of JSON encoded strings representing objects, one for each variant that belongs to this master product
 variants.available  | Boolean  |  Required - indicates the availability of this particular variant
 variants.product_sku  | String  |  Required - this is a 'key' that links this variant to its parent product, the value should be the SKU of the main product we are posting
 variants.sku  | String  |  Required - this is the SKU of this particular variant and should be unique
 variants.face_value  | Integer  |  Required conditional - if this product is a voucher, this shows the face value of this denomination
 variants.base_price  | Float  |  Required conditional - for non-voucher products all variants will have the same cost/base price but voucher denominations will have differing base prices
 variants.voucher_status  | Boolean  |  Required - indicated this variant is a voucher - you cannot mix vouchers and physical product variants this should be all or nothing and match the parent product
 variants.variant  | String  |  Required - for non voucher products this represents the reason for the variation such as size (medium large etc) or colour. For vouchers this represents the face value of this denomination
-brand_id  | Integer  | Optional - this indicates a brand. Note this is not the name of the brand, but the id of the brand as stored in GPS

source/includes/api/products/create_product_v3.md

@@ -360,7 +360,7 @@ brand_id | Integer | Optional - this indicates a brand. Note this is not the nam
 catalogue_id | Integer | Optional - the ID of the catalogue the product should belong to
 categories | Array of Integers | Optional - an array of category IDs that the product should belong to
 variant_type_id | Integer | Optional - the ID of a variant type in GPS (Colour = 1, Size = 2, Other = 8). Ignored for vouchers (since their variants are always denominations)
-variants | Array | Optional - an array of variants or denominations for this product
+variants | Array[Objects] | Optional - an array of variants or denominations that belong to this master product
 variants.variant | String | Required - for non-voucher products this represents the reason for the variation such as size (medium large etc) or colour. For vouchers this represents the face value of this denomination
 variants.sku | String | Required - this is the SKU of this particular variant and should be unique
 variants.face_value | Integer | Required (conditional) - if this product is a voucher, this shows the face value of this denomination

source/includes/api/products/update_product.md

@@ -2,9 +2,18 @@
 
 The update product API is available to update product information.
 
+<aside class="warning">
+    <b><u>IMPORTANT</u></b><br />
+    <div style="margin-left:25px;">
+        When updating an existing product that has variants, it is important that <b><u>all</u></b> variants be included in the update request.<br />
+        Products can only be updated using the V2 API; each variant should be provided as a JSON encoded string within the variants array.<br />
+        Any variants that are not included in the update request will be removed from the product.
+    </div>
+</aside>
+
 > Request
 
-``` http
+```http
 PATCH /api/v2/products/{product_id} HTTP/1.1
 Authorization: Token token=xxx
 Content-Type: application/json
@@ -22,11 +31,12 @@ Content-Type: application/json
         "currency": "USD",
         "availability_note": "available",
         "available": "yes",
-        "countries": [{
-            "country": "US",
-            "vat_rate": 0,
-            "delivery_charge": 0
-        }
+        "countries": [
+            {
+                "country": "US",
+                "vat_rate": 0,
+                "delivery_charge": 0
+            }
         ],
         "international_requirements": 0,
         "minimum_age": 21,
@@ -36,7 +46,9 @@ Content-Type: application/json
         "lowest_denomination": null,
         "catalogue_id": 1,
         "brand_id": 1,
-        "variants": ["{\"available\": 1, \"product_sku\": \"000123454\", \"sku\": \"000123457\", \"face_value\": null, \"base_price\": 100.0, \"voucher_status\": 0, \"variant\":\"test\" }"]
+        "variants": [
+            "{ \"available\":1, \"product_sku\":\"000123454\", \"sku\":\"000123457\", \"face_value\":null, \"base_price\":100.0, \"voucher_status\":0, \"variant\":\"test\" }"
+        ]
     }
 }
 ```
@@ -166,12 +178,12 @@ delivery_type_id  | Integer  |  Optional - delivery types in GPS are (but not li
 voucher  | Boolean  |  Optional - indicates if this product is to be treated as a voucher
 lowest_denomination  | Integer  | Optional conditional - if this product is considered a voucher this field should indicate the lowest denomination of voucher available
 catalogue_id  | Integer  |  Optional - The id of the catalogue the product should belong to
-variants  | Array  |  Optional - this is (somewhat convolutedly) a list of at 0 or more JSON encoded strings representing objects for a variant
+brand_id  | Integer  | Optional - this indicates a brand. Note this is not the name of the brand, but the id of the brand as stored in GPS
+variants  | Array[Strings]  |  Optional - an array of JSON encoded strings representing objects, one for each variant that belongs to this master product
 variants.available  | Boolean  |  Required for each variant added - indicates the availability of this particular variant
 variants.product_sku  | String  |  Required for each variant added - this is a 'key' that links this variant to its parent product, the value should be the SKU of the main product we are posting
 variants.sku  | String  |  Required for each variant added - this is the SKU of this particular variant and should be unique
 variants.face_value  | Integer  |  Required for each variant added - conditional - if this product is a voucher, this shows the face value of this denomination
 variants.base_price  | Float  |  Required for each variant added - conditional - for non-voucher products all variants will have the same cost/base price but voucher denominations will have differing base prices
 variants.voucher_status  | Boolean  |  Required for each variant added - indicated this variant is a voucher - you cannot mix vouchers and physical product variants this should be all or nothing and match the parent product
 variants.variant  | String  |  Required for each variant added - for non voucher products this represents the reason for the variation such as size (medium large etc) or colour. For vouchers this represents the face value of this denomination
-brand_id  | Integer  | Optional - this indicates a brand. Note this is not the name of the brand, but the id of the brand as stored in GPS