Workload Interfaces

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

Workload Interfaces Methods

Functionality	HTTP	URI
Request the list of the workload_interfaces (outside of the workloads or VENs scope). The `href` property in the API response is deprecated.	`GET`	`[api_version][workload_href]/interfaces`
Get an instance for the workload interface using the name. (DEPRECATED)	`GET`	`[api_version][workload_href]/interfaces/:name`
Directly creates a workload interface. The request payload was not changed. However, the `href` field in the API response is deprecated.	`POST`	`[api_version][workload_href] /interfaces`
Delete the workload interface with the name.(DEPRECATED)	`DELETE`	`[api_version][workload_href]/interfaces/:name`
Set the network manually and update the automatic network detection. (DEPRECATED)	`PUT`	`[api_version][workload_href]/interfaces/ :name/network`

Get Workload Network Interface

This API allows you to get information about one or all of the interfaces on a workload. You can retrieve workload interface information, including its connectivity status (up, down, or unknown), interface IP address, subnet mask size, default gateway IP address, and associated network.

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

GET [api_version][workload_href]/interfaces

Create Workload Network Interface

Directly creates a workload interface. The request payload was not changed. However, the href field in the API response is deprecated.

URI to Create a Workload Network Interface Configuration

POST [api_version][workload_href]/interfaces

Workload Interfaces Reference

This topic contains properties and examples for workload interfaces.

GET Properties for workload interfaces

Property	Description	Type	Required
`name`	Interface name.	String	Yes
`address`	The IP address is assigned to the interface.	String	Yes
`cidr_block`	The number of bits in the subnet (for example, /24 is 255.255.255.0).	Integer, Null	Yes
`default_gateway _address`	The default IP address of the default gateway.	String, Null	Yes
`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, Null	Yes
`network_detection _mode`	Network Detection Mode	String, Null	Yes
`friendly_name`	A user-friendly name is given to the interface.	String, Null	Yes
`network`	A network that the interface belongs to	Object, Null	Yes
`href`	DEPRECATED WITH NO REPLACEMENT	String	No

POST properties for workload interfaces

Properties	Description	Type	Required
`name`	The short, friendly name of the workload	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`: The state of the interface is unknown.	String	Yes
`address`	The IP address assigned to the interface. Reference to common schema `ip_address_format_validation.schema.json`	String	No
`cidr_block`	The number of bits in the subnet (for example, /24 is 255.255.255.0).	Integer	No
`default_ gateway_address`	The default IP address of the default gateway. Reference to common schema `ip_address_format_validation.schema.json`	String	No
`friendly_name`	User-friendly name given to the interface.	String	No
`href`	DEPRECATED WITH NO REPLACEMENT	String	No

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"}'

Examples

Request for all workload interfaces with a specific name

Request: GET /api/v2/orgs/:org_id/workloads/:workload_id/interfaces?name=eth0.public

The response includes the deprecated href field in the response:

[
   {
	"href": "/orgs/1/workloads/561bd65e-136c-4005-8aa2-bdc8af1b3600/interfaces/eth0.public"
	"name": "eth0.public",
	"cidr_block": null,
	link_state": null,
	"network_detection_mode": null,
	"friendly_name": null,
	"network": {
		"href": "/orgs/1/networks/366ff4c1-ec60-49be-a05f-3a5ccab09c2f"
	},
	"loopback": false,
	"address": "1.1.1.1",
	"default_gateway_address": null
   },
   {
	"href": "/orgs/1/workloads/561bd65e-136c-4005-8aa2-bdc8af1b3600/interfaces/eth0.public"
	"name": "eth0.public",
	"cidr_block": null,
	"link_state": null,
	"network_detection_mode": null,
	"friendly_name": null,
	"network": {
		"href": "/orgs/1/networks/366ff4c1-ec60-49be-a05f-3a5ccab09c2f"
	},
	"loopback": false,
	"address": "2.2.2.2",
	"default_gateway_address": null
}

API request/response creating new workload interface

Request: POST /api/v2/orgs/:org_id/workloads/:workload_id/interfaces

{
	"name": "eth1.private",
	"cidr_block": 32,
	"link_state": "up",
	"address": "99.99.99.7"
}

The Response body (with the href deprecated):

{
	"href": "/orgs/1/workloads/561bd65e-136c-4005-8aa2/interfaces/eth1.private"
	"name": "eth1.private",
	"cidr_block": 32,
	"link_state": "up",
	"network_detection_mode": "single_private_brn",
	"friendly_name": null,
	"network": {
		"href": "/orgs/1/networks/5b25c11d-4e95-42d3-abd2-488506e48b02"
	},
	"loopback": false,
	"address": "99.99.99.7",
	"default_gateway_address": null
}

API request deleting multiple workload interfaces (bundle delete)

Request: PUT /api/v2/orgs/:org_id/workloads/:workload_id/interfaces/delete

Successful delete

Payload - all interfaces with the name eth0.public and only one interface with the name eth1.private are deleted.

Response code - 200

{
	"name": "eth0.public"
},
{
	"name": "eth1.private",
	"address": "10.10.10.1"
}

REST APIs 25.1 Developer Guide