Considerations for ports and interfaces

The words "port" and "interface" have meanings that are different from meanings in other network operating systems. In the ArubaOS-CX operating system:

A port is the logical representation of a port.
An interface is the hardware representation of a port.
When creating a VLAN or LAG interface in the CLI, you are creating ports in the REST API.

Most resources have a hierarchical relationship. You must create the parent before you can create the child. However, interfaces do not have a parent that is clear from the resource hierarchy. Therefore, there are some things you do differently from other resources when creating and deleting interfaces:

Hardware interfaces are included in the database automatically. Considerations for interfaces apply to user-created interfaces such as VLAN interfaces or LAG interfaces.
When you insert a transceiver in the physical port, the port is automatically created. Because the port already exists, executing a POST request to create a port after a transceiver is inserted does not work.
Before you create a VLAN or LAG interface, you must create the port the interface will be referenced by.
When you create a port, if you choose a VRF other than the default VRF, you must create that VRF before you create the port.
When you create a port, you must explicitly designate the VRF that refers to the port. The POST method JSON model for a port includes the field vrf to designate this relationship.

The following example creates a port resource for VLAN 200. You must create the VLAN before you create the port:
```
POST "https://192.0.2.5/rest/v1/system/ports"
{
  "name": "vlan200",
  "admin": "up",
  "vrf": "/rest/v1/system/vrfs/default",
  "vlan_tag": "/rest/v1/system/vlans/200",
}
```
When you create a VLAN or LAG interface, you must explicitly designate the port that refers to this interface. The POST method JSON model includes the field referenced_by to designate this relationship.

The following example creates a VLAN interface:
```
POST "https://192.0.2.5/rest/v1/system/interfaces"
{
  "name": "vlan200",
  "referenced_by": "/rest/v1/system/ports/vlan200",
  "description": "referenced by /system/ports/vlan200",
  "type": "vlan",
  "user_config": {
    "admin": "up"
  }
}
```
Only the POST method JSON models for interfaces include the referenced_by field. The referenced_by field is not included in the response body for GET requests, and is not supported by the PUT method.
The interfaces resource does not support the DELETE method. After the interface is removed from all the resources that reference it, the interface is removed from the system automatically. This automatic removal is done through the same process that automatically removes resources that have no parent resource.

For example, to delete the VLAN interface created in the preceding example, "/rest/v1/system/interfaces/vlan200", you must use the PUT method to update port resource and remove the interface from the list of interfaces:
1. Get the configuration attributes of the port:
```
GET "https://192.0.2.5/rest/v1/system/ports/vlan200?selector=configuration"
```
2. Modify the JSON body by removing the vlan200 interface from the list of interfaces.
3. Use the modified JSON body as the request body for the PUT method request to the port:
```
PUT "https://192.0.2.5/rest/v1/system/ports/vlan200"
```
Hewlett Packard Enterprise recommends that you include referenced_by information in the description field when you create the interface. By including this information when the interface is created, you avoid having to query all possible referring resources (such as all ports that refer to a VLAN interface) when you want to remove the interface.