Workload Interfaces

This Public Stable API allows you to get network interface information from a workload, either for all interfaces on a workload or an individual interface. You can also configure (create) or delete an individual network interface configuration.

API Methods

Functionality	HTTP	URI
Get a collection of all network interfaces for a workload	`GET`	`[api_version][workload_href]/interfaces`
Get information about an individual network interface for a workload	`GET`	`[api_version][workload_href]/interfaces/:name`
Create a network interface configuration for an individual workload.	`POST`	`[api_version][workload_href]/interfaces`
Delete a workload network interface configuration.	`DELETE`	`[api_version][workload_href]/interfaces/:name`

Workload HREF and Interface Names

Before you can get network interface information for a workload, you need to know the workload's HREF and the name of the interface. To obtain a workload's HREF, use the workloads API to get a collection of workloads.

In response for getting workloads, each workload is identified by an HREF, and each network interface is identified by its name:

{
    "href": "/orgs/2/workloads/3e3e17ce-XXXX-42b4-XXXX-1d4d3328b342",
    "deleted": false,
    "name": standalone_dev,
    "description": null,
    "hostname": "hrm-db-prod1",
    "service_principal_name": null,
    "public_ip": "xxx.0.2.10",
    "external_data_set": null,
    "external_data_reference": null,
    "interfaces": [
      {
        "name": "eth0.public",
        "address": "xxx.0.2.10",
        "cidr_block": 32,
        "default_gateway_address": null,
        "link_state": "up",
        "network_id": 3,
        "network_detection_mode": "manual",
        "friendly_name": null
      },
      {
        "name": "eth0",
        "address": "xx.10.10.10",
        "cidr_block": null,
        "default_gateway_address": "xx.0.10.10",
        "link_state": "up",
        "network_id": 3,
        "network_detection_mode": "single_private_brn",
        "friendly_name": "Friendly eth0"
      }
    ],
    ....

Get Workload Network Interface

This API lets you get information about one or all of the interfaces on a workload. You can retrieve workload interface information such as its connectivity (up, down, unknown), interface IP address, number of bits in the subnet, the IP address of the default gateway, and the associated network.

URI to Get a Collection of a Workload's Network Interfaces

GET [api_version][workload_href]/interfaces

URI to Get an Individual Workload Network Interface

GET [api_version][workload_href]/interfaces/:name

Query Parameters for GET

Parameter	Description	Type	Requiured
`name`	Name of the network interface on the workload.	String	Yes
`org_id`	Organization	Integer	Yes
`workload_id`	Workload UUID	String	Yes

Request Body Properties for GET

Property	Description	Type
`name`	Interface name.	String
`cidr_block`	The number of bits in the subnet (for example, /24 is 255.255.255.0).	Integer
`link_state`	State of the interface connection, which is one of three values: `up`: Interface is communicating. `down`: Interface is not communicating. `unknown`: The state of the interface is unknown.	String
`address`	The IP address is assigned to the interface.	String
`default_gateway_address`	The default IP address of the default gateway.	Integer
`friendly_name`	Friendly name given to the interface.	String

Curl Command Get Collection of Interface Statuses

curl -i -X GET https://pce.my-company.com:8443/api/v2/3/workloads/12/interface_statuses -H "Accept: application/json" -u $KEY:$TOKEN

Create Workload Network Interface

After you have obtained a workload's HREF, you can use that HREF to make an API call that creates a new network interface configuration for the workload.

URI to Create a Workload Network Interface Configuration

POST [api_version][workload_href]/interfaces

Request Parameters for POST

Parameter	Description	Type	Required
`name`	Name of the network interface on the workload.	String	Yes
`org_id`	Organization	Integer	Yes
`workload_id`	Workload UUIUD	String	Yes

Response Properties for POST

Property	Description	Type	Required
`name`	Interface name.	String	Yes
`link_state`	State of the interface connection, which is one of three values: `up`: Interface is communicating. `down`: Interface is not communicating. `unknown`: State of the interface is unknown.	String	Yes
`address`	The IP address assigned to the interface.	String	No
`default_gateway_address`	The default IP address of the default gateway.	Integer	No
`friendly_name`	Friendly name given to the interface.	String	No
`cidr_block`	The number of bits in the subnet (for example, /24 is 255.255.255.0).	Integer

Request Body

 {
    "name": "eth0.public",
    "address": "192.0.2.0",
    "cidr_block": 32,
    "default_gateway_address": 255.255.255.0,
    "link_state": "up",         
 }

Curl Command Create Network Interface

curl -i -X POST https://pce.my-company.com:8443/api/v2/orgs/2/workloads/xxxxxxxx-c4e9-44e7-8a31-e86acf6b276c/interfaces -H "Content-Type: application/json" -u $KEY:$TOKEN -d '{"name": "eth0.public", "address": "192.0.2.0","cidr_block": "32", "default_gateway_address": "255.255.255.0", "link_state": "up"}'

Delete Workload Network Interface

To delete a workload's network interface, you need the workload HREF and the name of the workload's network interface. Both values can be obtained in the response when you get an individual workload or a collection of workloads.

Once you have obtained a workload's HREF and the network interface name, you can use those values to make an API call that deletes the specified network interface from the workload.

Request Parameters DELETE

Parameter	Description	Type	Required
`name`	Name of the network interface on the workload.	String	Yes
`org_id`	Organization	Integer	Yes
`workload_id`	Workload UUIUD	String	Yes

URI to Delete a Workload Network Interface Configuration

DELETE [api_version][workload_href]/interfaces/:name

Curl Command Delete Network Interface

curl -i -X DELETE https://pce.my-company.com:8443/api/v2/orgs/2/workloads/xxxxxxxx-c4e9-44e7-8a31-e86acf6b276c/interfaces/eth0 -H "Accept: application/json" -u $KEY:$TOKEN

REST APIs for 22.2