13.2. Network Interfaces Sub-Collection

The nics sub-collection represents all network interface devices on a virtual machine. A nic representation contains the following elements:

Note

The icons used in the properties column of this table are described in Table 7.1, “Element property icons”

Table 13.5. Elements for virtual machine network interfaces

Element Type Description Properties
link rel="statistics" relationship A link to the statistics sub-collection for a virtual machine's network interface statistics.
network id= GUID A reference to the network which the interface should be connected.
interface enumerated The type of driver used for the nic. A list of enumerated values is available in capabilities. See Section 6.1.11, “NIC Interface Types”.
mac address= string The MAC address of the interface.

Example 13.9. An XML representation of a network interface

<nic id="7a3cff5e-3cc4-47c2-8388-9adf16341f5e" 
  ref="/api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/nics/
  7a3cff5e-3cc4-47c2-8388-9adf16341f5e">
    <link rel="statistics"
      href="/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/nics/
      7a3cff5e-3cc4-47c2-8388-9adf16341f5e/statistics"/>   
    <name>nic1</name>
    <interface>virtio</interface>
    <mac address="00:1a:4a:16:84:07"/>
    <network id="00000000-0000-0000-0000-000000000009"
      href="/api/networks/00000000-0000-0000-0000-000000000009"/>
    <vm id="cdc0b102-fbfe-444a-b9cb-57d2af94f401"
      href="/api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401"/>
</nic>

When adding a new network interface, the name and network elements are required. Identify the network element with the id attribute or name element.
An API user modifies a network interface with a PUT request.
PUT /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/nics/
7a3cff5e-3cc4-47c2-8388-9adf16341f5e HTTP/1.1
Accept: application/xml
Content-type: application/xml

<nic>
    <name>nic2</name>
    <network id="00000000-0000-0000-0000-000000000010"/>
    <type>e1000</type>
</nic>
An API user removes a network interface with a DELETE request.
DELETE /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/nics/
7a3cff5e-3cc4-47c2-8388-9adf16341f5e HTTP/1.1

HTTP/1.1 204 No Content

13.2.1. Network Interface Statistics

Each virtual machine's network interface exposes a statistics sub-collection for network interface statistics. Each statistic contains the following elements:

Table 13.6. Elements for a virtual machine's network interface statistics

Element Type Description
name string The unique identifier for the statistic entry.
description string A plain text description of the statistic.
unit string The unit or rate to measure the statistical values.
type One of GAUGE or COUNTER The type of statistic measures.
values type= One of INTEGER or DECIMAL The data type for the statistical values that follow.
value complex A data set that contains datum.
datum see values type An individual piece of data from a value.
nic id= relationship A relationship to the containing nic resource.

The following table lists the statistic types for network interfaces on virtual machines.

Table 13.7. Virtual machine NIC statistic types

Name
Description
data.current.rx
The rate in bytes per second of data received.
data.current.tx
The rate in bytes per second of data transmitted.
errors.total.rx
Total errors from receiving data.
errors.total.tx
Total errors from transmitting data.

Example 13.10. An XML representation of a virtual machine's NIC statistics sub-collection

<statistics>
    <statistic id="ecd0559f-e88f-3330-94b4-1f091b0ffdf7"
      href="/api/vms/3a42530e-3bc5-4094-829d-489257894c2a/nics/
      6cd08e76-57c0-41ba-a728-7eba46ae1e36/statistics/
      ecd0559f-e88f-3330-94b4-1f091b0ffdf7">
        <name>data.current.rx</name>
        <description>Receive data rate</description>
        <values type="DECIMAL">
            <value>
                <datum>0</datum>
            </value>
        </values>
        <type>GAUGE</type>
        <unit>BYTES_PER_SECOND</unit>
        <nic id="6cd08e76-57c0-41ba-a728-7eba46ae1e36"
          href="/api/vms/3a42530e-3bc5-4094-829d-489257894c2a/
          nics/6cd08e76-57c0-41ba-a728-7eba46ae1e36"/>
    </statistic>
    ...
</statistics>

Note

This statistics sub-collection is read-only.