Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?


Interface Descriptions (API)

Besides main parameters of network interfaces like name, speed and port mode, Apstra also configures a description for physical interfaces and aggregated logical interfaces (so called port channels). Interface description is automatically generated if the following conditions are met:

  1. The interface is connected to a peer.
  2. The interface belongs to leaf, spine or generic system.
  3. The peer interface belongs to leaf, spine, or generic system with virtual network endpoint on this server.

The generated description has the form <facing_|to.><peer-device-label>[:peer-interface-name]. Examples:

  • facing_spine2:Ethernet1/2
  • to.server1:eth0
  • to.server2

The prefix of the name is facing_ if the peer is leaf, spine or external router. The prefix is to. in case peer device is an L2 or L3 server. The peer interface name part is present only when the peer device is controlled by Apstra.

Apstra REST API - Interface descriptions

The Apstra API is able to change the auto-generated interface description. However, there is no such functionality in the Apstra UI.

The interface description may contain ASCII characters with codes 33-126 and spaces, except "?", which is interpreted as a command-completion. The description length is limited to 240 characters, which is the longest possible length across supported switch models.

Interfaces are stored internally as graph nodes with certain set of properties. Description is one of these properties. To modify the description, use the generic API to interact with graph nodes.

API - Obtain interface configuration

To obtain interface configuration, send GET request to https://aos-server/api/blueprints/{blueprint-id}/nodes/{interface-node-id}.


API - Create or modify interface description

To create or modify interface description, send PATCH request to https://aos-server/api/blueprints/{blueprint-id}/nodes/{interface-node-id} with a valid JSON. The JSON should contain the "description" field with a valid data.


API - Delete interface description

To delete custom interface description and get back to automatic description generation, set the description to empty value.



Subsequent GET request will show that the description was automatically generated.