Add VM SSH key endpoints (#505)

* Add VM SSH key endpoints

* update SSH key create parameters

components/schemas/common/Capability.yml

@@ -109,3 +109,5 @@ enum:
   - "virtual-machines-deploy"
   - "virtual-machines-console"
   - "virtual-machines-lock"
+  - "virtual-machines-ssh-keys-manage"
+

components/schemas/containers/instances/InstanceState.yml

@@ -10,7 +10,6 @@ allOf:
         enum:
           - new
           - starting
-          - reimaging
           - migrating
           - running
           - stopping

components/schemas/vms/ssh-keys/VirtualMachineSshKey.yml

@@ -0,0 +1,44 @@
+title: VirtualMachineSshKey
+type: object
+description: |
+  Describes an SSH key used to access a virtual machine.
+properties:
+  id:
+    $ref: ../../ID.yml
+  name:
+    type: string
+    description: A user-defined name for the SSH key.
+  identifier:
+    $ref: ../../Identifier.yml
+  creator:
+    $ref: ../../creators/CreatorScope.yml
+  environment_id:
+    $ref: ../../ID.yml
+  hub_id:
+    $ref: ../../ID.yml
+  state:
+    allOf:
+      - required:
+          - current
+        properties:
+          current:
+            description: The current state of the SSH key.
+            type: string
+            enum:
+              - live
+              - deleting
+              - deleted
+      - $ref: ../../State.yml
+  public_key:
+    type: string
+    description: The public key value of this SSH key.
+required:
+  - id
+  - name
+  - identifier
+  - creator
+  - environment_id
+  - hub_id
+  - state
+  - public_key
+

platform/api.yml

@@ -697,6 +697,8 @@ paths:
     $ref: "./paths/virtual-machines/images/base.yml"
   "/v1/virtual-machines/{virtualMachineId}/sos":
     $ref: paths/virtual-machines/sos/sos.yml
+  "/v1/virtual-machines/ssh-keys":
+    $ref: paths/virtual-machines/ssh-keys/ssh-keys.yml
 
   # --Utility
   "/v1/utils/resource/lookup":

platform/paths/sdn/network.yml

@@ -8,7 +8,7 @@ get:
     - name: networkId
       in: path
       required: true
-      description: The ID of the Network.
+      description: The ID of the network.
       schema:
         type: string
     - name: include
@@ -72,18 +72,18 @@ patch:
             - creators
             - environments
   requestBody:
-    description: Parameters for updating a Network.
+    description: Parameters for updating a network.
     content:
       application/json:
         schema:
           type: object
           properties:
             name:
               type: string
-              description: The name of the Network.
+              description: The name of the network.
   responses:
     200:
-      description: Returns a Network.
+      description: Returns a network.
       content:
         application/json:
           schema:
@@ -108,12 +108,12 @@ delete:
     - name: networkId
       in: path
       required: true
-      description: The ID of the Network.
+      description: The ID of the network.
       schema:
         type: string
   responses:
     202:
-      description: Returns a Job Descriptor.
+      description: Returns a job descriptor.
       content:
         application/json:
           schema:

platform/paths/sdn/networks.yml

@@ -38,7 +38,7 @@ get:
           state:
             type: string
             description: |
-              `filter[state]=value1,value2` state filtering will allow you to filter by the Network's current state.
+              `filter[state]=value1,value2` state filtering will allow you to filter by the network's current state.
     - $ref: ../../../components/parameters/SortParam.yml
     - $ref: ../../../components/parameters/PageParam.yml
   responses:
@@ -84,7 +84,7 @@ post:
             - creators
             - environments
   requestBody:
-    description: Parameters for creating a new Network.
+    description: Parameters for creating a new network.
     content:
       application/json:
         schema:
@@ -97,25 +97,25 @@ post:
           properties:
             name:
               type: string
-              description: The name of the Network.
+              description: The name of the network.
             identifier:
               type: string
-              description: A Network identifier used to construct http calls that specifically use this Network over another.
+              description: A network identifier used to construct http calls that specifically use this network over another.
             acl:
               anyOf:
                 - $ref: ../../../components/schemas/common/ACL.yml 
                 - type: "null"
             cluster:
               type: string
-              description: The infrastructure Cluster the Environments belonging to this Network belong to.
+              description: The infrastructure cluster the environments belonging to this network belong to.
             environments:
-              description: An array of Environment Ids
+              description: An array of environment Ids
               type: array
               items:
                 type: string
   responses:
     201:
-      description: Returns a Network.
+      description: Returns a network.
       content:
         application/json:
           schema:

platform/paths/virtual-machines/includes/VirtualMachineSshIncludes.yml

@@ -0,0 +1,14 @@
+title: VirtualMachineSshIncludes
+description: All includable resources linkable to the given virtual machine SSH key.
+type: object
+properties:
+  creators:
+    $ref: ../../../../components/schemas/includes/CreatorInclude.yml
+  environments:
+    type: object
+    additionalProperties:
+      $ref: ../../../../components/schemas/environments/Environment.yml
+  environments:identifiers:
+    type: object
+    additionalProperties:
+      $ref: ../../../../components/schemas/ID.yml

platform/paths/virtual-machines/ssh-keys/ssh-key.yml

@@ -0,0 +1,132 @@
+get:
+  operationId: "getVirtualMachineSshKey"
+  summary: Get Virtual Machine SSH Key
+  description: |
+    Retrieves a single virtual machine SSH key by ID.
+
+    Requires the `virtual-machines-ssh-keys-manage` capability.
+  tags:
+    - Virtual Machines
+  parameters:
+    - name: sshKeyId
+      description: The ID of the virtual machine SSH key.
+      in: path
+      required: true
+      schema:
+        type: string
+    - name: include
+      in: query
+      required: false
+      description: |
+        A comma-separated list of include values. Included resources will show up under the root document's `include` field.
+        In the case of applying an include to a collection of resources, if multiple resources share the same include, it will only appear once in the return.
+      schema:
+        type: array
+        items:
+          type: string
+          enum:
+            - creators
+            - environments
+  responses:
+    200:
+      description: Returns the requested virtual machine SSH key.
+      content:
+        application/json:
+          schema:
+            type: object
+            required:
+              - data
+            properties:
+              data:
+                $ref: ../../../../components/schemas/vms/ssh-keys/VirtualMachineSshKey.yml
+              includes:
+                $ref: ../includes/VirtualMachineSshIncludes.yml
+    default:
+      $ref: ../../../../components/responses/errors/DefaultError.yml
+
+patch:
+  operationId: "updateVirtualMachineSshKey"
+  summary: Update Virtual Machine SSH Key
+  description: |
+    Updates the specified virtual machine SSH key.
+
+    Requires the `virtual-machines-ssh-keys-manage` capability.
+  tags:
+    - Virtual Machine
+  parameters:
+    - name: sshKeyId
+      description: The ID of the SSH key.
+      in: path
+      required: true
+      schema:
+        type: string
+    - name: include
+      in: query
+      required: false
+      description: |
+        A comma-separated list of include values. Included resources will show up under the root document's `include` field.
+        In the case of applying an include to a collection of resources, if multiple resources share the same include, it will only appear once in the return.
+      schema:
+        type: array
+        items:
+          type: string
+          enum:
+            - creators
+            - environments
+  requestBody:
+    description: Parameters for updating the virtual machine SSH key.
+    content:
+      application/json:
+        schema:
+          type: object
+          properties:
+            name:
+              type: string
+              description: The name of the virtual machine SSH key.
+            identifier:
+              type: string
+              description: The identifier of the virtual machine SSH key.
+  responses:
+    200:
+      description: Returns the updated virtual machine SSH key.
+      content:
+        application/json:
+          schema:
+            type: object
+            required:
+              - data
+            properties:
+              data:
+                $ref: ../../../../components/schemas/vms/ssh-keys/VirtualMachineSshKey.yml
+              includes:
+                $ref: ../includes/VirtualMachineSshIncludes.yml
+    default:
+      $ref: ../../../../components/responses/errors/DefaultError.yml
+
+delete:
+  operationId: "deleteVirtualMachineSshKey"
+  summary: Delete Virtual Machine SSH Key
+  description: Requires the `virtual-machines-ssh-keys-manage` capability.
+  tags:
+    - Virtual Machines
+  parameters:
+    - name: sshKeyId
+      description: The ID of the virtual machine SSH key to delete.
+      in: path
+      required: true
+      schema:
+        type: string
+  responses:
+    202:
+      description: Returns a job descriptor.
+      content:
+        application/json:
+          schema:
+            type: object
+            required:
+              - data
+            properties:
+              data:
+                $ref: ../../../../components/schemas/jobs/JobDescriptor.yml
+    default:
+      $ref: ../../../../components/responses/errors/DefaultError.yml