Port

This page describes operations you can perform on ports. List, create, get details for, update, and delete.

List Port

List all visible ports.

Synchronous / Asynchronous

  • Synchronous

Request

HTTP Request Method

  • GET

HTTP Request Path

{endpoint}/v2.0/ports

HTTP Request Parameters

Parameter Style Type Format Enumeration Description Required
description query string - - Port description. no
device_id query string hyph-uuid-or-empty - The Id of device (i.e physical port id for baremetal). no
device_owner query string - - The name of the port owner no
id query string hyph-uuid - Port unique id. no
mac_address query string - - The MAC address of the port. no
name query string - - Port name. no
network_id query string hyph-uuid - The ID of network this port belongs to. no
segmentation_id query integer - - The segmenation ID used for this port (i.e. for vlan type it is vlan tag) no
segmentation_type query string - [‘flat’, ‘vlan’] The segmentation type used for this port (i.e. vlan) no
status query string - - The port status. no
tenant_id query string non-hyph-uuid-or-empty - The owner name of port. no

Response

HTTP Response Code List

Response Code Description
200 OK
400 Bad Request
401 UnAuthorized
404 Not Found
500 Internal Server Error

HTTP Response Parameters

Parameter Type Format Description
ports array<object> Port -
admin_state_up boolean - Administrative state of Port (supported when device_owner starts with “compute:”)
allowed_address_pairs array<object> - Allowed address pairs
ip_address string cidr-or-ipv4 -
mac_address string mac -
description string - Port description.
device_id string hyph-uuid-or-empty The Id of device (i.e physical port id for baremetal).
device_owner string - The name of the port owner
fixed_ips array<object> - List of fixes IP addresses assign to port.
ip_address string - The IP address assign to port within subnet.
subnet_id string hyph-uuid The ID of subnet from which IP address is allocated.
id string hyph-uuid Port unique id.
mac_address string - The MAC address of the port.
managed_by_service boolean - Set to true if only admin can modify it. Normal user has only read access.
name string - Port name.
network_id string hyph-uuid The ID of network this port belongs to.
segmentation_id integer - The segmenation ID used for this port (i.e. for vlan type it is vlan tag)
segmentation_type string - The segmentation type used for this port (i.e. vlan)
status string - The port status.
tags object - Port tags.
tenant_id string non-hyph-uuid-or-empty The owner name of port.

Examples

Sample Request Body

This operation does not send a request body.

Sample Response Body

{
  "ports": [
    {
      "admin_state_up": true,
      "allowed_address_pairs": [],
      "description": "Example port 1 description.",
      "device_id": "b269b8c0-1a42-4464-9314-4396e51e5107",
      "device_owner": "compute:Tokyo-DC1",
      "fixed_ips": [
        {
          "ip_address": "10.161.54.13",
          "subnet_id": "93bb920c-19be-4026-8cc7-564bfcd41456"
        }
      ],
      "id": "81c3b7d4-eae2-4858-ab76-fa56117b8ab4",
      "mac_address": "26:8d:42:f6:c2:c4",
      "managed_by_service": true,
      "name": "Example port 1",
      "network_id": "ba199c9e-ff09-4d7d-a164-ff61c66cf01f",
      "segmentation_id": 0,
      "segmentation_type": "flat",
      "status": "ACTIVE",
      "tags": {
        "keyword1": "value1",
        "keyword2": "value2"
      },
      "tenant_id": "a4d8a821cdc347a3bf65764067f75df9"
    },
    {
      "admin_state_up": true,
      "allowed_address_pairs": [
        {
          "ip_address": "10.0.0.50",
          "mac_address": "2d:0d:9a:96:9c:eb"
        },
        {
          "ip_address": "10.0.0.51",
          "mac_address": "2d:0d:9a:14:65:6d"
        }
      ],
      "description": "Example port 2 description.",
      "device_id": "b269b8c0-1a42-4464-9314-4396e51e5107",
      "device_owner": "physical_port",
      "fixed_ips": [
        {
          "ip_address": "10.161.55.13",
          "subnet_id": "64887030-9623-4a20-bcb0-c92e8a2496ca"
        }
      ],
      "id": "268d42f6-c25c-4f24-90fe-11324f0dd7ab",
      "mac_address": "b3:e9:45:86:a9:dd",
      "managed_by_service": true,
      "name": "Example port 2",
      "network_id": "ba199c9e-ff09-4d7d-a164-ff61c66cf01f",
      "segmentation_id": 100,
      "segmentation_type": "vlan",
      "status": "DOWN",
      "tags": {
        "keyword1": "value1",
        "keyword2": "value2"
      },
      "tenant_id": "6a156ddf2ecd497ca786ff2da6df5aa8"
    }
  ]
}

Create Port

Create port.

Synchronous / Asynchronous

  • Asynchronous

Request

HTTP Request Method

  • POST

HTTP Request Path

{endpoint}/v2.0/ports

HTTP Request Parameters

Parameter Style Type Format Enumeration Default Description Required
port plain object Port - - - yes
admin_state_up plain boolean - - True Administrative state of Port (supported when device_owner starts with “compute:”) no
allowed_address_pairs plain array<object> - - null Allowed address pairs no
ip_address plain string cidr-or-ipv4 - - - yes
mac_address plain string mac - See notes. - no
description plain string - - “” Port description. no
device_id plain string hyph-uuid-or-empty - “” The Id of device (i.e physical port id for baremetal). no
device_owner plain string - - “” The name of the port owner no
fixed_ips plain array<object> - - null List of fixes IP addresses assign to port. no
ip_address plain string - - See notes. The IP address assign to port within subnet. no
subnet_id plain string hyph-uuid - See notes. The ID of subnet from which IP address is allocated. no
mac_address plain string - - See notes. The MAC address of the port. no
name plain string - - “” Port name. no
network_id plain string hyph-uuid - - The ID of network this port belongs to. yes
segmentation_id plain integer - - 0 The segmenation ID used for this port (i.e. for vlan type it is vlan tag) no
segmentation_type plain string - [‘flat’, ‘vlan’] “flat” The segmentation type used for this port (i.e. vlan) no
tags plain object - - {} Port tags. no
tenant_id plain string non-hyph-uuid-or-empty - See notes. The owner name of port. no

Note

allowed_address_pairs.mac_address: Same to port.mac_address.

fixed_ips.ip_address: The first available IP address in the subnet.

fixed_ips.subnet_id: The ID of subnet whose CIDR contains the IP address.

mac_address: The randomized value which starts with “fa:16:3e”, and unique to the given network.

tenant_id: The ID of default tenant to which user belongs.

Response

HTTP Response Code List

Response Code Description
200 OK
400 Bad Request
401 UnAuthorized
404 Not Found
409 Conflict
500 Internal Server Error

HTTP Response Parameters

Parameter Type Format Description
port object Port -
admin_state_up boolean - Administrative state of Port (supported when device_owner starts with “compute:”)
allowed_address_pairs array<object> - Allowed address pairs
ip_address string cidr-or-ipv4 -
mac_address string mac -
description string - Port description.
device_id string hyph-uuid-or-empty The Id of device (i.e physical port id for baremetal).
device_owner string - The name of the port owner
fixed_ips array<object> - List of fixes IP addresses assign to port.
ip_address string - The IP address assign to port within subnet.
subnet_id string hyph-uuid The ID of subnet from which IP address is allocated.
id string hyph-uuid Port unique id.
mac_address string - The MAC address of the port.
managed_by_service boolean - Set to true if only admin can modify it. Normal user has only read access.
name string - Port name.
network_id string hyph-uuid The ID of network this port belongs to.
segmentation_id integer - The segmenation ID used for this port (i.e. for vlan type it is vlan tag)
segmentation_type string - The segmentation type used for this port (i.e. vlan)
status string - The port status.
tags object - Port tags.
tenant_id string non-hyph-uuid-or-empty The owner name of port.

Examples

Sample Request Body

{
  "port": {
    "admin_state_up": true,
    "allowed_address_pairs": [],
    "description": "Example port 1 description.",
    "device_id": "b269b8c0-1a42-4464-9314-4396e51e5107",
    "device_owner": "compute:Tokyo-DC1",
    "fixed_ips": [
      {
        "ip_address": "10.161.54.13",
        "subnet_id": "93bb920c-19be-4026-8cc7-564bfcd41456"
      }
    ],
    "mac_address": "26:8d:42:f6:c2:c4",
    "name": "Example port 1",
    "network_id": "ba199c9e-ff09-4d7d-a164-ff61c66cf01f",
    "segmentation_id": 0,
    "segmentation_type": "flat",
    "tags": {
      "keyword1": "value1",
      "keyword2": "value2"
    },
    "tenant_id": "a4d8a821cdc347a3bf65764067f75df9"
  }
}

Sample Response Body

{
  "port": {
    "admin_state_up": true,
    "allowed_address_pairs": [],
    "description": "Example port 1 description.",
    "device_id": "b269b8c0-1a42-4464-9314-4396e51e5107",
    "device_owner": "compute:Tokyo-DC1",
    "fixed_ips": [
      {
        "ip_address": "10.161.54.13",
        "subnet_id": "93bb920c-19be-4026-8cc7-564bfcd41456"
      }
    ],
    "id": "81c3b7d4-eae2-4858-ab76-fa56117b8ab4",
    "mac_address": "26:8d:42:f6:c2:c4",
    "managed_by_service": true,
    "name": "Example port 1",
    "network_id": "ba199c9e-ff09-4d7d-a164-ff61c66cf01f",
    "segmentation_id": 0,
    "segmentation_type": "flat",
    "status": "PENDING_CREATE",
    "tags": {
      "keyword1": "value1",
      "keyword2": "value2"
    },
    "tenant_id": "a4d8a821cdc347a3bf65764067f75df9"
  }
}

Show Port

Show details for port.

Synchronous / Asynchronous

  • Synchronous

Request

HTTP Request Method

  • GET

HTTP Request Path

{endpoint}/v2.0/ports/{port_id}

HTTP Request Parameters

Parameter Style Type Format Enumeration Description Required
port_id URI string hyph-uuid - - yes

Response

HTTP Response Code List

Response Code Description
200 OK
400 Bad Request
401 UnAuthorized
404 Not Found
500 Internal Server Error

HTTP Response Parameters

Parameter Type Format Description
port object Port -
admin_state_up boolean - Administrative state of Port (supported when device_owner starts with “compute:”)
allowed_address_pairs array<object> - Allowed address pairs
ip_address string cidr-or-ipv4 -
mac_address string mac -
description string - Port description.
device_id string hyph-uuid-or-empty The Id of device (i.e physical port id for baremetal).
device_owner string - The name of the port owner
fixed_ips array<object> - List of fixes IP addresses assign to port.
ip_address string - The IP address assign to port within subnet.
subnet_id string hyph-uuid The ID of subnet from which IP address is allocated.
id string hyph-uuid Port unique id.
mac_address string - The MAC address of the port.
managed_by_service boolean - Set to true if only admin can modify it. Normal user has only read access.
name string - Port name.
network_id string hyph-uuid The ID of network this port belongs to.
segmentation_id integer - The segmenation ID used for this port (i.e. for vlan type it is vlan tag)
segmentation_type string - The segmentation type used for this port (i.e. vlan)
status string - The port status.
tags object - Port tags.
tenant_id string non-hyph-uuid-or-empty The owner name of port.

Examples

Sample Request Body

This operation does not send a request body.

Sample Response Body

{
  "port": {
    "admin_state_up": true,
    "allowed_address_pairs": [],
    "description": "Example port 1 description.",
    "device_id": "b269b8c0-1a42-4464-9314-4396e51e5107",
    "device_owner": "compute:Tokyo-DC1",
    "fixed_ips": [
      {
        "ip_address": "10.161.54.13",
        "subnet_id": "93bb920c-19be-4026-8cc7-564bfcd41456"
      }
    ],
    "id": "81c3b7d4-eae2-4858-ab76-fa56117b8ab4",
    "mac_address": "26:8d:42:f6:c2:c4",
    "managed_by_service": true,
    "name": "Example port 1",
    "network_id": "ba199c9e-ff09-4d7d-a164-ff61c66cf01f",
    "segmentation_id": 0,
    "segmentation_type": "flat",
    "status": "ACTIVE",
    "tags": {
      "keyword1": "value1",
      "keyword2": "value2"
    },
    "tenant_id": "a4d8a821cdc347a3bf65764067f75df9"
  }
}

Update Port

Update port.

Synchronous / Asynchronous

  • Asynchronous

Request

HTTP Request Method

  • PUT

HTTP Request Path

{endpoint}/v2.0/ports/{port_id}

HTTP Request Parameters

Parameter Style Type Format Enumeration Description Required
port_id URI string hyph-uuid - - yes
port plain object Port - - yes
admin_state_up plain boolean - - Administrative state of Port (supported when device_owner starts with “compute:”) no
allowed_address_pairs plain array<object> - - Allowed address pairs no
allowed_address_pairs.ip_address plain string cidr-or-ipv4 - - no
allowed_address_pairs.mac_address plain string mac - - no
description plain string - - Port description. no
device_id plain string hyph-uuid-or-empty - The Id of device (i.e physical port id for baremetal). no
device_owner plain string - - The name of the port owner no
fixed_ips plain array<object> - - List of fixes IP addresses assign to port. no
fixed_ips.ip_address plain string - - The IP address assign to port within subnet. no
fixed_ips.subnet_id plain string hyph-uuid - The ID of subnet from which IP address is allocated. no
name plain string - - Port name. no
segmentation_id plain integer - - The segmenation ID used for this port (i.e. for vlan type it is vlan tag) no
segmentation_type plain string - [‘flat’, ‘vlan’] The segmentation type used for this port (i.e. vlan) no
tags plain object - - Port tags. no

Response

HTTP Response Code List

Response Code Description
200 OK
400 Bad Request
401 UnAuthorized
404 Not Found
409 Conflict
500 Internal Server Error

HTTP Response Parameters

Parameter Type Format Description
port object Port -
admin_state_up boolean - Administrative state of Port (supported when device_owner starts with “compute:”)
allowed_address_pairs array<object> - Allowed address pairs
ip_address string cidr-or-ipv4 -
mac_address string mac -
description string - Port description.
device_id string hyph-uuid-or-empty The Id of device (i.e physical port id for baremetal).
device_owner string - The name of the port owner
fixed_ips array<object> - List of fixes IP addresses assign to port.
ip_address string - The IP address assign to port within subnet.
subnet_id string hyph-uuid The ID of subnet from which IP address is allocated.
id string hyph-uuid Port unique id.
mac_address string - The MAC address of the port.
managed_by_service boolean - Set to true if only admin can modify it. Normal user has only read access.
name string - Port name.
network_id string hyph-uuid The ID of network this port belongs to.
segmentation_id integer - The segmenation ID used for this port (i.e. for vlan type it is vlan tag)
segmentation_type string - The segmentation type used for this port (i.e. vlan)
status string - The port status.
tags object - Port tags.
tenant_id string non-hyph-uuid-or-empty The owner name of port.

Examples

Sample Request Body

{
  "port": {
    "admin_state_up": true,
    "allowed_address_pairs": [],
    "description": "Example port 1 description.",
    "device_id": "b269b8c0-1a42-4464-9314-4396e51e5107",
    "device_owner": "compute:Tokyo-DC1",
    "fixed_ips": [
      {
        "ip_address": "10.161.54.13",
        "subnet_id": "93bb920c-19be-4026-8cc7-564bfcd41456"
      }
    ],
    "name": "Example port 1",
    "segmentation_id": 0,
    "segmentation_type": "flat",
    "tags": {
      "keyword1": "value1",
      "keyword2": "value2"
    }
  }
}

Sample Response Body

{
  "port": {
    "admin_state_up": true,
    "allowed_address_pairs": [],
    "description": "Example port 1 description.",
    "device_id": "b269b8c0-1a42-4464-9314-4396e51e5107",
    "device_owner": "compute:Tokyo-DC1",
    "fixed_ips": [
      {
        "ip_address": "10.161.54.13",
        "subnet_id": "93bb920c-19be-4026-8cc7-564bfcd41456"
      }
    ],
    "id": "81c3b7d4-eae2-4858-ab76-fa56117b8ab4",
    "mac_address": "26:8d:42:f6:c2:c4",
    "managed_by_service": true,
    "name": "Example port 1",
    "network_id": "ba199c9e-ff09-4d7d-a164-ff61c66cf01f",
    "segmentation_id": 0,
    "segmentation_type": "flat",
    "status": "PENDING_UPDATE",
    "tags": {
      "keyword1": "value1",
      "keyword2": "value2"
    },
    "tenant_id": "a4d8a821cdc347a3bf65764067f75df9"
  }
}

Delete Port

Delete port.

Synchronous / Asynchronous

  • Asynchronous

Request

HTTP Request Method

  • DELETE

HTTP Request Path

{endpoint}/v2.0/ports/{port_id}

HTTP Request Parameters

Parameter Style Type Format Enumeration Description Required
port_id URI string hyph-uuid - - yes

Response

HTTP Response Code List

Response Code Description
204 No Content
400 Bad Request
401 UnAuthorized
404 Not Found
409 Conflict
500 Internal Server Error

HTTP Response Parameters

This operation does not receive a response body.

Examples

Sample Request Body

This operation does not send a request body.

Sample Response Body

This operation does not receive a response body.