Merge pull request #1005 from joyent/ether/v3.0-hwp

new hardware_product endpoints for v3.0

docs/json-schema/common.json

@@ -2,6 +2,47 @@
   "$comment" : "NOTE: This file is for human reference ONLY. For programmatic use, use the GET '/schema/common/$schema_name' endpoints, or within conch itself, json-schema/common.yaml.",
   "$schema" : "http://json-schema.org/draft-07/schema#",
   "definitions" : {
+    "HardwareProductSpecification" : {
+      "description" : "this is the structure of the hardware_product.specification database column",
+      "properties" : {
+        "chassis" : {
+          "properties" : {
+            "memory" : {
+              "properties" : {
+                "dimms" : {
+                  "$comment" : "items are in slot order, as in device report /dimms/*",
+                  "items" : {
+                    "properties" : {
+                      "slot" : {
+                        "$comment" : "compared to device report /dimms/*/memory-locator/memory-serial-number",
+                        "type" : "string"
+                      }
+                    },
+                    "type" : "object"
+                  },
+                  "minItems" : 1,
+                  "type" : "array"
+                }
+              },
+              "type" : "object"
+            }
+          },
+          "type" : "object"
+        },
+        "disk_size" : {
+          "$comment" : "property names correspond to device report /disks/<disk serial>/model",
+          "additionalProperties" : {
+            "$comment" : "property values are compared to device report /disks/<disk serial>/block_sz",
+            "type" : "integer"
+          },
+          "required" : [
+            "_default"
+          ],
+          "type" : "object"
+        }
+      },
+      "type" : "object"
+    },
     "device_asset_tag" : {
       "pattern" : "^\\S+$",
       "type" : "string"

docs/json-schema/query_params.json

@@ -114,6 +114,19 @@
       },
       "type" : "object"
     },
+    "HardwareProductSpecification" : {
+      "additionalProperties" : false,
+      "properties" : {
+        "path" : {
+          "format" : "json-pointer",
+          "type" : "string"
+        }
+      },
+      "required" : [
+        "path"
+      ],
+      "type" : "object"
+    },
     "NotifyUsers" : {
       "additionalProperties" : false,
       "description" : "used for operations where email can optionally be sent",

docs/json-schema/request.json

@@ -436,6 +436,9 @@
         }
       ]
     },
+    "HardwareProductSpecification" : {
+      "$ref" : "common.json#/definitions/HardwareProductSpecification"
+    },
     "HardwareProductUpdate" : {
       "additionalProperties" : false,
       "minProperties" : 1,
@@ -631,9 +634,14 @@
           "$ref" : "common.json#/definitions/mojo_standard_placeholder"
         },
         "specification" : {
-          "description" : "json blob of additional data",
+          "$comment" : "json blob of additional data for hardware_product.specification (TO BE RESTRUCTURED SOON)",
           "oneOf" : [
             {
+              "$comment" : "Note that contentSchema is not validated automatically; the data must be json-decoded first and then the schema applied manually",
+              "contentMediaType" : "application/json",
+              "contentSchema" : {
+                "$ref" : "common.json#/definitions/HardwareProductSpecification"
+              },
               "type" : "string"
             },
             {

docs/json-schema/response.json

@@ -1608,19 +1608,17 @@
           ]
         },
         "sku" : {
-          "oneOf" : [
-            {
-              "$ref" : "common.json#/definitions/mojo_standard_placeholder"
-            },
-            {
-              "type" : "null"
-            }
-          ]
+          "$ref" : "common.json#/definitions/mojo_standard_placeholder"
         },
         "specification" : {
-          "description" : "json blob of additional data",
+          "$comment" : "json blob of additional data for hardware_product.specification (TO BE RESTRUCTURED SOON)",
           "oneOf" : [
             {
+              "$comment" : "Note that contentSchema is not validated automatically; the data must be json-decoded first and then the schema applied manually",
+              "contentMediaType" : "application/json",
+              "contentSchema" : {
+                "$ref" : "common.json#/definitions/HardwareProductSpecification"
+              },
               "type" : "string"
             },
             {
@@ -1684,7 +1682,49 @@
     },
     "HardwareProducts" : {
       "items" : {
-        "$ref" : "/definitions/HardwareProduct"
+        "additionalProperties" : false,
+        "properties" : {
+          "alias" : {
+            "$ref" : "common.json#/definitions/mojo_standard_placeholder"
+          },
+          "created" : {
+            "format" : "date-time",
+            "type" : "string"
+          },
+          "generation_name" : {
+            "oneOf" : [
+              {
+                "type" : "string"
+              },
+              {
+                "type" : "null"
+              }
+            ]
+          },
+          "id" : {
+            "$ref" : "common.json#/definitions/uuid"
+          },
+          "name" : {
+            "$ref" : "common.json#/definitions/mojo_standard_placeholder"
+          },
+          "sku" : {
+            "$ref" : "common.json#/definitions/mojo_standard_placeholder"
+          },
+          "updated" : {
+            "format" : "date-time",
+            "type" : "string"
+          }
+        },
+        "required" : [
+          "id",
+          "name",
+          "alias",
+          "generation_name",
+          "sku",
+          "created",
+          "updated"
+        ],
+        "type" : "object"
       },
       "type" : "array",
       "uniqueItems" : true

docs/modules/Conch::Controller::HardwareProduct.md

@@ -36,6 +36,23 @@ Updates an existing hardware\_product.
 
 ### delete
 
+### set\_specification
+
+Uses the URI fragment as a json pointer to determine the path within the `specification` property
+to operate on. New data is written, and existing data is overwritten without regard to type (so long
+as it conforms to the schema).
+
+After the update operation, the `specification` property must validate against
+[common.json#/definitions/HardwareProductSpecification](../json-schema/common.json#/definitions/HardwareProductSpecification).
+
+### delete\_specification
+
+Uses the URI fragment as a json pointer to determine the path within the `specification` property
+to operate on. All of the data at the indicated path is deleted.
+
+After the delete operation, the `specification` property must validate against
+[common.json#/definitions/HardwareProductSpecification](../json-schema/common.json#/definitions/HardwareProductSpecification).
+
 ## LICENSING
 
 Copyright Joyent, Inc.

docs/modules/Conch::Route::HardwareProduct.md

@@ -32,6 +32,8 @@ Identifiers accepted: `id`, `sku`, `name` and `alias`.
 
 ### `POST /hardware_product/:hardware_product_id_or_other`
 
+Updates the indicated hardware product.
+
 Identifiers accepted: `id`, `sku`, `name` and `alias`.
 
 - Requires system admin authorization
@@ -40,11 +42,56 @@ Identifiers accepted: `id`, `sku`, `name` and `alias`.
 
 ### `DELETE /hardware_product/:hardware_product_id_or_other`
 
+Deactivates the indicated hardware product, preventing it from being used. All devices using this
+hardware must be switched to other hardware first.
+
 Identifiers accepted: `id`, `sku`, `name` and `alias`.
 
 - Requires system admin authorization
 - Response: `204 No Content`
 
+### `PUT /hardware_product/:hardware_product_id_or_other/specification?path=:path_to_data`
+
+Sets a specific part of the json blob data in the `specification` field, treating the URI fragment
+as the JSON pointer to the data to be added or modified. Existing data at the path is overwritten
+without regard to type, so long as the JSON Schema is respected. For example, this existing
+`specification` field and this request:
+
+```
+{
+  "foo": { "bar": 123 },
+  "x": { "y": [ 1, 2, 3 ] }
+}
+
+POST /hardware_product/:hardware_product_id_or_other/specification?path=/foo/bar/baz  { "hello":1 }
+```
+
+Results in this data in `specification`, changing the data type at node `/foo/bar`:
+
+```
+{
+  "foo": { "bar": { "baz": { "hello": 1 } } },
+  "x": { "y": [ 1, 2, 3 ] }
+}
+```
+
+- Requires system admin authorization
+- Request: after the update operation, the `specification` property must validate against
+[common.json#/definitions/HardwareProductSpecification](../json-schema/common.json#/definitions/HardwareProductSpecification).
+- Response: `204 No Content`
+
+### `DELETE /hardware_product/:hardware_product_id_or_other/specification?path=:path_to_data`
+
+Deletes a specific part of the json blob data in the `specification` field, treating the URI
+fragment as the JSON pointer to the data to be removed. All other properties in the json blob
+are left untouched.
+
+After the delete operation, the `specification` property must validate against
+[common.json#/definitions/HardwareProductSpecification](../json-schema/common.json#/definitions/HardwareProductSpecification).
+
+- Requires system admin authorization
+- Response: `204 No Content`
+
 ## LICENSING
 
 Copyright Joyent, Inc.

json-schema/common.yaml

@@ -97,5 +97,33 @@ definitions:
       - type: string
         format: email
       - $ref: /definitions/mojo_relaxed_placeholder
+  HardwareProductSpecification:
+    description: this is the structure of the hardware_product.specification database column
+    type: object
+    properties:
+      disk_size:
+        type: object
+        $comment: property names correspond to device report /disks/<disk serial>/model
+        required:
+          - _default
+        additionalProperties:
+          $comment: property values are compared to device report /disks/<disk serial>/block_sz
+          type: integer
+      chassis:
+        type: object
+        properties:
+          memory:
+            type: object
+            properties:
+              dimms:
+                $comment: items are in slot order, as in device report /dimms/*
+                type: array
+                minItems: 1
+                items:
+                  type: object
+                  properties:
+                    slot:
+                      $comment: compared to device report /dimms/*/memory-locator/memory-serial-number
+                      type: string
 
 # vim: set sts=2 sw=2 et :

json-schema/query_params.yaml

@@ -188,5 +188,14 @@ definitions:
     properties:
       no_save_db:
         $ref: /definitions/boolean_integer_default_false
+  HardwareProductSpecification:
+    type: object
+    additionalProperties: false
+    required:
+      - path
+    properties:
+      path:
+        type: string
+        format: json-pointer
 
 # vim: set sts=2 sw=2 et :

json-schema/request.yaml

@@ -246,6 +246,9 @@ definitions:
         - purpose
         - bios_firmware
         - cpu_type
+  HardwareProductSpecification:
+    # this is just a hack for the /hardware_product/*/specification endpoints
+    $ref: common.yaml#/definitions/HardwareProductSpecification
   HardwareProductUpdate:
     type: object
     additionalProperties: false
@@ -262,9 +265,13 @@ definitions:
       hardware_vendor_id:
         $ref: common.yaml#/definitions/uuid
       specification:
-        description: json blob of additional data
+        $comment: json blob of additional data for hardware_product.specification (TO BE RESTRUCTURED SOON)
         oneOf:
-          - type: string
+          - $comment: Note that contentSchema is not validated automatically; the data must be json-decoded first and then the schema applied manually
+            type: string
+            contentMediaType: application/json
+            contentSchema:
+              $ref: common.yaml#/definitions/HardwareProductSpecification
           - type: 'null'
       sku:
         $ref: common.yaml#/definitions/mojo_standard_placeholder

json-schema/response.yaml

@@ -712,7 +712,35 @@ definitions:
     type: array
     uniqueItems: true
     items:
-      $ref: /definitions/HardwareProduct
+      type: object
+      additionalProperties: false
+      required:
+        - id
+        - name
+        - alias
+        - generation_name
+        - sku
+        - created
+        - updated
+      properties:
+        id:
+          $ref: common.yaml#/definitions/uuid
+        name:
+          $ref: common.yaml#/definitions/mojo_standard_placeholder
+        alias:
+          $ref: common.yaml#/definitions/mojo_standard_placeholder
+        generation_name:
+          oneOf:
+            - type: string
+            - type: 'null'
+        sku:
+          $ref: common.yaml#/definitions/mojo_standard_placeholder
+        created:
+          type: string
+          format: date-time
+        updated:
+          type: string
+          format: date-time
   HardwareProduct:
     type: object
     additionalProperties: false
@@ -778,13 +806,15 @@ definitions:
           - type: string
           - type: 'null'
       sku:
-        oneOf:
-          - $ref: common.yaml#/definitions/mojo_standard_placeholder
-          - type: 'null'
+        $ref: common.yaml#/definitions/mojo_standard_placeholder
       specification:
-        description: json blob of additional data
+        $comment: json blob of additional data for hardware_product.specification (TO BE RESTRUCTURED SOON)
         oneOf:
-          - type: string
+          - $comment: Note that contentSchema is not validated automatically; the data must be json-decoded first and then the schema applied manually
+            type: string
+            contentMediaType: application/json
+            contentSchema:
+              $ref: common.yaml#/definitions/HardwareProductSpecification
           - type: 'null'
       rack_unit_size:
         $ref: common.yaml#/definitions/positive_integer