255 lines
5.0 KiB
ReStructuredText
255 lines
5.0 KiB
ReStructuredText
.. -*- rst -*-
|
|
|
|
=============
|
|
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).
|
|
|
|
|
|
List Ports
|
|
==========
|
|
|
|
.. rest_method:: GET /v1/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.
|
|
|
|
``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
|
|
|
|
|
|
List Detailed Ports
|
|
===================
|
|
|
|
.. 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 <https://tools.ietf.org/html/rfc6902>`_.
|
|
|
|
.. 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
|