From 14e48ec273ffb57c1db333f387f5df9d49fa4077 Mon Sep 17 00:00:00 2001 From: Devananda van der Veen Date: Thu, 5 May 2016 16:22:45 -0700 Subject: [PATCH] Update the api-ref documentation for Ports This updates the API documentation for the Ports resource class, replacing many of the samples and adding more verbiage to each property. It's not perfect, but this is vastly more correct than the current docs. Co-Authored-By: Vladyslav Drok Change-Id: I559ef1e921aa8e2f2f1a8bd6ed18e0a39ecc4687 --- .../source/baremetal-api-v1-nodes-ports.inc | 91 ++++ api-ref/source/baremetal-api-v1-ports.inc | 396 ++++++++++-------- api-ref/source/index.rst | 1 + api-ref/source/parameters.yaml | 89 ++-- .../samples/node-port-detail-response.json | 22 + .../samples/node-port-list-response.json | 18 + .../source/samples/port-create-request.json | 4 + .../source/samples/port-create-response.json | 18 + .../samples/port-list-detail-response.json | 22 + .../source/samples/port-list-response.json | 18 + .../source/samples/port-update-request.json | 7 + .../source/samples/port-update-response.json | 18 + 12 files changed, 494 insertions(+), 210 deletions(-) create mode 100644 api-ref/source/baremetal-api-v1-nodes-ports.inc create mode 100644 api-ref/source/samples/node-port-detail-response.json create mode 100644 api-ref/source/samples/node-port-list-response.json create mode 100644 api-ref/source/samples/port-create-request.json create mode 100644 api-ref/source/samples/port-create-response.json create mode 100644 api-ref/source/samples/port-list-detail-response.json create mode 100644 api-ref/source/samples/port-list-response.json create mode 100644 api-ref/source/samples/port-update-request.json create mode 100644 api-ref/source/samples/port-update-response.json 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" +}