diff --git a/api-ref/source/baremetal-api-v1-nodes-ports.inc b/api-ref/source/baremetal-api-v1-nodes-ports.inc new file mode 100644 index 0000000000..9bfba9be04 --- /dev/null +++ b/api-ref/source/baremetal-api-v1-nodes-ports.inc @@ -0,0 +1,91 @@ +.. -*- rst -*- + +==================================== +Listing Ports by Node (nodes, ports) +==================================== + +Given a Node identifier (``uuid`` or ``name``), the API exposes the list of, +and details of, all Ports associated with that Node. + +These endpoints do not allow modification of the Ports; that should be done +by accessing the Port resources under the ``/v1/ports`` endpoint. + + +List Ports by Node +=================== + +.. rest_method:: GET /v1/nodes/{node_ident}/ports + +Return a list of bare metal Ports associated with ``node_ident``. + +Normal response code: 200 + +Error codes: TBD + +Request +------- + +.. rest_parameters:: parameters.yaml + + - node_ident: node_ident + - fields: fields + - limit: limit + - marker: marker + - sort_dir: sort_dir + - sort_key: sort_key + +Response +-------- + +.. rest_parameters:: parameters.yaml + + - ports: ports + - uuid: uuid + - address: port_address + - links: links + +**Example list of a Node's Ports:** + +.. literalinclude:: samples/node-port-list-response.json + + +List detailed Ports by Node +=========================== + +.. rest_method:: GET /v1/nodes/{node_ident}/ports/detail + +Return a detailed list of bare metal Ports associated with ``node_ident``. + +Normal response code: 200 + +Error codes: TBD + +Request +------- + +.. rest_parameters:: parameters.yaml + + - node_ident: node_ident + - fields: fields + - limit: limit + - marker: marker + - sort_dir: sort_dir + - sort_key: sort_key + +Response +-------- + +.. rest_parameters:: parameters.yaml + + - ports: ports + - uuid: uuid + - address: port_address + - node_uuid: node_uuid + - extra: extra + - created_at: created_at + - updated_at: updated_at + - links: links + +**Example details of a Node's Ports:** + +.. literalinclude:: samples/node-port-detail-response.json diff --git a/api-ref/source/baremetal-api-v1-ports.inc b/api-ref/source/baremetal-api-v1-ports.inc index 6846abf260..f60eb4ab0f 100644 --- a/api-ref/source/baremetal-api-v1-ports.inc +++ b/api-ref/source/baremetal-api-v1-ports.inc @@ -4,205 +4,251 @@ Ports (ports) ============= +Listing, Searching, Creating, Updating, and Deleting of bare metal Port +resources are done through the ``ports`` resource. +All Ports must be associated to a Node when created. This association +can be changed, though the request may be rejected if either the current +or destination Node are in a transitive state (eg, in the process of deploying) +or are in a state that would be non-deterministically affected by such a change +(e.g., there is an active user instance on the Node). -Show port details -================= - -.. rest_method:: GET /v1/ports/{port_id} - -Shows details for a port. - - -Normal response codes: 200 -Error response codes:413,405,404,403,401,400,503, - - -Request -------- - -.. rest_parameters:: parameters.yaml - - - port_id: uuid - - fields: fields - - - - -Response Example ----------------- - -TODO - - - - - - - - - - -Update port -=========== - -.. rest_method:: PATCH /v1/ports/{port_id} - -Updates a port. - - -Normal response codes: 200 -Error response codes:413,415,405,404,403,401,400,503,409, - - -Request -------- - -.. rest_parameters:: parameters.yaml - - - port_id: uuid - - - - -Response Example ----------------- - -TODO - - - - - - - - - - - - -Delete port -=========== - -.. rest_method:: DELETE /v1/ports/{port_id} - -Deletes a port. - -Error response codes:204,413,415,405,404,403,401,400,503,409, - - -Request -------- - -.. rest_parameters:: parameters.yaml - - - port_id: uuid - - - - - - - - - - - - - - - -List ports with details -======================= - -.. rest_method:: GET /v1/ports/detail - -Lists all ports with details. - - -Normal response codes: 200 -Error response codes:413,405,404,403,401,400,503, - - -Request -------- - - - - - -Response Example ----------------- - -TODO - - - - - - - - - - -Create port -=========== - -.. rest_method:: POST /v1/ports - -Creates a port. - -Error response codes:201,413,415,405,404,403,401,400,503,409, - - -Request -------- - - - - - - - - - - - - - - - - -List ports +List Ports ========== -.. rest_method:: GET /v1/ports +.. rest_method:: GET /v1/ports -Lists all ports. +Return a list of bare metal Ports. Some filtering is possible by passing in +some parameters with the request. +By default, this query will return the uuid and address for each Port. -Normal response codes: 200 -Error response codes:413,405,404,403,401,400,503, +``node`` query parameter was added in API microversion 1.6. If both +``node_uuid`` and ``node`` are specified in the request, ``node_uuid`` +will be used to filter results. +API microversion 1.8 added the ``fields`` Request parameter. When specified, +this causes the content of the Response to include only the specified fields, +rather than the default set. + +Normal response code: 200 Request ------- +.. rest_parameters:: parameters.yaml + + - node: r_port_node_ident + - node_uuid: r_port_node_uuid + - address: r_port_address + - fields: fields + - limit: limit + - marker: marker + - sort_dir: sort_dir + - sort_key: sort_key + +Response +-------- + +.. rest_parameters:: parameters.yaml + + - ports: ports + - uuid: uuid + - address: port_address + - links: links + +**Example Port list response:** + +.. literalinclude:: samples/port-list-response.json + :language: javascript +Create Port +=========== + +.. rest_method:: POST /v1/ports + +Creates a new Port resource. + +This method requires a Node UUID and the physical hardware address for the Port +(MAC address in most cases). + +Normal response code: 201 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - node_uuid: node_uuid + - address: port_address + +**Example Port creation request:** + +.. literalinclude:: samples/port-create-request.json + :language: javascript + +Response +-------- + +.. rest_parameters:: parameters.yaml + + - uuid: uuid + - address: port_address + - node_uuid: node_uuid + - extra: extra + - created_at: created_at + - updated_at: updated_at + - links: links + +**Example Port creation response:** + +.. literalinclude:: samples/port-create-response.json + :language: javascript -Response Example ----------------- +List Port Detail +================= -TODO +.. rest_method:: GET /v1/ports/detail + +Return a list of bare metal Ports, with detailed information. + +``node`` query parameter was added in API microversion 1.6. If both +``node_uuid`` and ``node`` are specified in the request, ``node_uuid`` +will be used to filter results. + +Normal response code: 200 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - node: r_port_node_ident + - node_uuid: r_port_node_uuid + - address: r_port_address + - limit: limit + - marker: marker + - sort_dir: sort_dir + - sort_key: sort_key + +Response +-------- + +.. rest_parameters:: parameters.yaml + + - ports: ports + - uuid: uuid + - address: port_address + - node_uuid: node_uuid + - extra: extra + - created_at: created_at + - updated_at: updated_at + - links: links + +**Example detailed Port list response:** + +.. literalinclude:: samples/port-list-detail-response.json + :language: javascript +Show Port Details +================= + +.. rest_method:: GET /v1/ports/{port_id} + +Show details for the given Port. + +API microversion 1.8 added the ``fields`` Request parameter. When specified, +this causes the content of the Response to include only the specified fields, +rather than the default set. + +Normal response code: 200 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - port_id: port_ident + - fields: fields + +Response +-------- + +.. rest_parameters:: parameters.yaml + + - uuid: uuid + - address: port_address + - node_uuid: node_uuid + - extra: extra + - created_at: created_at + - updated_at: updated_at + - links: links + +**Example Port details:** + +.. literalinclude:: samples/port-create-response.json + :language: javascript +Update a Port +============== + +.. rest_method:: PATCH /v1/ports/{port_id} + +Update a Port. + +Normal response code: 200 + +Request +------- + +The BODY of the PATCH request must be a JSON PATCH document, adhering to +`RFC 6902 `_. + +.. rest_parameters:: parameters.yaml + + - port_id: port_ident + +**Example Port update request:** + +.. literalinclude:: samples/port-update-request.json + :language: javascript + +Response +-------- + +.. rest_parameters:: parameters.yaml + + - uuid: uuid + - address: port_address + - node_uuid: node_uuid + - extra: extra + - created_at: created_at + - updated_at: updated_at + - links: links + +**Example Port update response:** + +.. literalinclude:: samples/port-update-response.json + :language: javascript +Delete Port +=========== +.. rest_method:: DELETE /v1/ports/{port_id} +Delete a Port. +Normal response code: 204 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - port_id: port_ident diff --git a/api-ref/source/index.rst b/api-ref/source/index.rst index dbe36f040d..866ef12300 100644 --- a/api-ref/source/index.rst +++ b/api-ref/source/index.rst @@ -19,6 +19,7 @@ is presented in this document. Significant changes may be noted inline. .. include:: baremetal-api-v1-node-management.inc .. include:: baremetal-api-v1-node-passthru.inc .. include:: baremetal-api-v1-ports.inc +.. include:: baremetal-api-v1-nodes-ports.inc .. include:: baremetal-api-v1-drivers.inc .. include:: baremetal-api-v1-chassis.inc diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml index 887e323fa4..98f089c951 100644 --- a/api-ref/source/parameters.yaml +++ b/api-ref/source/parameters.yaml @@ -141,6 +141,28 @@ r_maintenance: in: query required: false type: boolean +r_port_address: + description: | + Filter the list of returned Ports, and only return the ones with + specified physical hardware address, typically MAC, or an empty set if not + found. + in: query + required: false + type: string +r_port_node_ident: + description: | + Filter the list of returned Ports, and only return the ones associated + with this specific node (name or UUID), or an empty set if not found. + in: query + required: false + type: string +r_port_node_uuid: + description: | + Filter the list of returned Ports, and only return the ones associated + with this specific node UUID, or an empty set if not found. + in: query + required: false + type: string r_provision_state: description: | Filter the list of returned nodes, and only return those with the specified @@ -222,19 +244,8 @@ console_enabled: type: boolean created_at: description: | - The date and time when the resource was created. - - The date and time stamp format is `ISO 8601 - `_: - - :: - - CCYY-MM-DDThh:mm:ss±hh:mm - - For example, ``2015-08-27T09:49:58-05:00``. - - The ``±hh:mm`` value, if included, is the time zone as an offset - from UTC. + The date and time when the resource was created, + `ISO 8601 `_ format. in: body required: true type: string @@ -274,7 +285,7 @@ extra: A set of one or more arbitrary metadata key and value pairs. in: body - required: false + required: true type: object hosts: description: | @@ -290,15 +301,17 @@ id: type: string inspection_finished_at: description: | - The date and time when the inspection process started. - May be "null" + The date and time when the resource was created, + `ISO 8601 `_ format. + May be "null". in: body required: true type: string inspection_started_at: description: | - The date and time when the inspection process started. - May be "null" + The date and time when the resource was created, + `ISO 8601 `_ format. + May be "null". in: body required: true type: string @@ -380,6 +393,12 @@ node_name: in: body required: false type: string +node_uuid: + description: | + UUID of the Node this resource belongs to. + in: body + required: true + type: string nodes: description: | Links to the collection of nodes contained in @@ -394,6 +413,18 @@ persistent: in: body required: true type: boolean +port_address: + description: | + Physical hardware address of this network Port, typically the HW MAC address. + in: body + required: true + type: string +ports: + description: | + A collection of Port resources. + in: body + required: true + type: array power_state: description: | The current power state of this Node. Usually, "power on" or "power off", but may be "None" @@ -415,7 +446,8 @@ provision_state: type: string provision_updated_at: description: | - The date and time when the provision_state last changed. + The date and time when the resource was created, + `ISO 8601 `_ format. ``null`` if the node is not being provisioned. in: body required: true @@ -486,22 +518,9 @@ target_raid_config: type: JSON updated_at: description: | - The date and time when the resource was updated. - - The date and time stamp format is `ISO 8601 - `_: - - :: - - CCYY-MM-DDThh:mm:ss±hh:mm - - For example, ``2015-08-27T09:49:58-05:00``. - - The ``±hh:mm`` value, if included, is the time zone as an offset - from UTC. In the previous example, the offset value is ``-05:00``. - - If the ``updated_at`` date and time stamp is not set, its value is - ``null``. + The date and time when the resource was updated, + `ISO 8601 `_ format. + May be "null". in: body required: true type: string diff --git a/api-ref/source/samples/node-port-detail-response.json b/api-ref/source/samples/node-port-detail-response.json new file mode 100644 index 0000000000..0cb3367179 --- /dev/null +++ b/api-ref/source/samples/node-port-detail-response.json @@ -0,0 +1,22 @@ +{ + "ports" : [ + { + "extra" : {}, + "address" : "22:22:22:22:22:22", + "updated_at" : "2016-05-05T22:48:52+00:00", + "node_uuid" : "ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb", + "links" : [ + { + "rel" : "self", + "href" : "http://127.0.0.1:6385/v1/ports/c933a251-486f-4c27-adb2-8b5f59bd9cd2" + }, + { + "href" : "http://127.0.0.1:6385/ports/c933a251-486f-4c27-adb2-8b5f59bd9cd2", + "rel" : "bookmark" + } + ], + "created_at" : "2016-05-05T22:30:57+00:00", + "uuid" : "c933a251-486f-4c27-adb2-8b5f59bd9cd2" + } + ] +} diff --git a/api-ref/source/samples/node-port-list-response.json b/api-ref/source/samples/node-port-list-response.json new file mode 100644 index 0000000000..5606a25e51 --- /dev/null +++ b/api-ref/source/samples/node-port-list-response.json @@ -0,0 +1,18 @@ +{ + "ports" : [ + { + "uuid" : "c933a251-486f-4c27-adb2-8b5f59bd9cd2", + "links" : [ + { + "href" : "http://127.0.0.1:6385/v1/ports/c933a251-486f-4c27-adb2-8b5f59bd9cd2", + "rel" : "self" + }, + { + "href" : "http://127.0.0.1:6385/ports/c933a251-486f-4c27-adb2-8b5f59bd9cd2", + "rel" : "bookmark" + } + ], + "address" : "22:22:22:22:22:22" + } + ] +} diff --git a/api-ref/source/samples/port-create-request.json b/api-ref/source/samples/port-create-request.json new file mode 100644 index 0000000000..b4dad27767 --- /dev/null +++ b/api-ref/source/samples/port-create-request.json @@ -0,0 +1,4 @@ +{ + "node_uuid": "ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb", + "address": "11:11:11:11:11:11" +} \ No newline at end of file diff --git a/api-ref/source/samples/port-create-response.json b/api-ref/source/samples/port-create-response.json new file mode 100644 index 0000000000..95ccdc6d50 --- /dev/null +++ b/api-ref/source/samples/port-create-response.json @@ -0,0 +1,18 @@ +{ + "created_at" : "2016-05-05T22:30:57.924480+00:00", + "links" : [ + { + "rel" : "self", + "href" : "http://127.0.0.1:6385/v1/ports/c933a251-486f-4c27-adb2-8b5f59bd9cd2" + }, + { + "href" : "http://127.0.0.1:6385/ports/c933a251-486f-4c27-adb2-8b5f59bd9cd2", + "rel" : "bookmark" + } + ], + "extra" : {}, + "address" : "11:11:11:11:11:11", + "updated_at" : null, + "node_uuid" : "ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb", + "uuid" : "c933a251-486f-4c27-adb2-8b5f59bd9cd2" +} diff --git a/api-ref/source/samples/port-list-detail-response.json b/api-ref/source/samples/port-list-detail-response.json new file mode 100644 index 0000000000..00b6add816 --- /dev/null +++ b/api-ref/source/samples/port-list-detail-response.json @@ -0,0 +1,22 @@ +{ + "ports" : [ + { + "node_uuid" : "ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb", + "extra" : {}, + "updated_at" : "2016-05-05T22:48:52+00:00", + "uuid" : "c933a251-486f-4c27-adb2-8b5f59bd9cd2", + "address" : "22:22:22:22:22:22", + "links" : [ + { + "href" : "http://127.0.0.1:6385/v1/ports/c933a251-486f-4c27-adb2-8b5f59bd9cd2", + "rel" : "self" + }, + { + "href" : "http://127.0.0.1:6385/ports/c933a251-486f-4c27-adb2-8b5f59bd9cd2", + "rel" : "bookmark" + } + ], + "created_at" : "2016-05-05T22:30:57+00:00" + } + ] +} diff --git a/api-ref/source/samples/port-list-response.json b/api-ref/source/samples/port-list-response.json new file mode 100644 index 0000000000..b1c30132a3 --- /dev/null +++ b/api-ref/source/samples/port-list-response.json @@ -0,0 +1,18 @@ +{ + "ports" : [ + { + "address" : "11:11:11:11:11:11", + "uuid" : "c933a251-486f-4c27-adb2-8b5f59bd9cd2", + "links" : [ + { + "rel" : "self", + "href" : "http://127.0.0.1:6385/v1/ports/c933a251-486f-4c27-adb2-8b5f59bd9cd2" + }, + { + "rel" : "bookmark", + "href" : "http://127.0.0.1:6385/ports/c933a251-486f-4c27-adb2-8b5f59bd9cd2" + } + ] + } + ] +} diff --git a/api-ref/source/samples/port-update-request.json b/api-ref/source/samples/port-update-request.json new file mode 100644 index 0000000000..fe4a0c6470 --- /dev/null +++ b/api-ref/source/samples/port-update-request.json @@ -0,0 +1,7 @@ +[ + { + "path" : "/address", + "value" : "22:22:22:22:22:22", + "op" : "replace" + } +] diff --git a/api-ref/source/samples/port-update-response.json b/api-ref/source/samples/port-update-response.json new file mode 100644 index 0000000000..98d135929c --- /dev/null +++ b/api-ref/source/samples/port-update-response.json @@ -0,0 +1,18 @@ +{ + "node_uuid" : "ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb", + "extra" : {}, + "updated_at" : "2016-05-05T22:48:52+00:00", + "uuid" : "c933a251-486f-4c27-adb2-8b5f59bd9cd2", + "address" : "22:22:22:22:22:22", + "links" : [ + { + "href" : "http://127.0.0.1:6385/v1/ports/c933a251-486f-4c27-adb2-8b5f59bd9cd2", + "rel" : "self" + }, + { + "href" : "http://127.0.0.1:6385/ports/c933a251-486f-4c27-adb2-8b5f59bd9cd2", + "rel" : "bookmark" + } + ], + "created_at" : "2016-05-05T22:30:57+00:00" +}