Explore Cisco
How to Buy

Have an account?

  •   Personalized content
  •   Your products and support

Need an account?

Create an account

Cisco IOS XE REST API Management Reference Guide

Bias-Free Language

The documentation set for this product strives to use bias-free language. For the purposes of this documentation set, bias-free is defined as language that does not imply discrimination based on age, disability, gender, racial identity, ethnic identity, sexual orientation, socioeconomic status, and intersectionality. Exceptions may be present in the documentation due to language that is hardcoded in the user interfaces of the product software, language used based on RFP documentation, or language that is used by a referenced third-party product. Learn more about how Cisco is using Inclusive Language.

Book Contents
Find Matches in This Book
Available Languages

Results

Updated:
February 21, 2018

Chapter: L2 Interfaces

L2 Interfaces

Resource Summary for L2 Interfaces

HTTP Method
Resource
URL (BaseURL)
GET
POST
PUT
DELETE

L2 Interfaces

/api/v1/l2interfaces

Y

Y

N

N

/api/v1/ l2interfaces/{if-id}

Y

N

Y

Y

/api/v1/l2interfaces/{if-id}/state

Y

N

Y

N

L2 Interfaces

History

 

Release
Modification

IOS XE 3.13

Introduced for the CSR1000V platform

IOS XE 3.14

Added the bridge-id property

IOS XE 3.14

Introduced for ASR1001-X and ASR1002-X platforms

Properties: Interface Schema

Applies to L3 interface APIs: /api/v1/interfaces/{if-id}/state

Property
Type
Required for POST and PUT
Description

kind

string

Not Applicable

Object type

if-name

string

Mandatory

Ethernet interface name

Example: gigabitethenet3

description

string

Optional

Description for the interface.

If this property is not present, the default behavior is to remove the description, if one exists.

svc-instance-list

array

Mandatory

List of service instances for VLANs

svc-instance

number

Mandatory

(sub-property of svc-instance-list)

Service instance number.

Do not use the same svc-instance number in two entries.

Range: 1 to 8000

Example 1 : Correct use of unique svc-instance numbers for two entries in the svc-instance-list:

[
{ 'svc-instance': 5001,
….
}
{ 'svc-instance': 5002,
…
}
]
 

Example 2 : Incorrect use of same svc-instance number in two entries:

[
{ 'svc-instance': 5001,
….
}
{ 'svc-instance': 5001,
…
}
]

encap-type

string

Mandatory

(sub-property of svc-instance-list)

Encapsulation type

Values: "dot1q" or "untag"

In the svc-instance-list, only one entry can define encap-type as "untag".

Example 1 : Correct

instance-list: [
{ 'svc-instance': 5001,
'encap-type': 'untag'
}
{ 'svc-instance': 5002,
'encap-type': 'dot1q'
….
}
{ 'svc-instance': 5003,
'encap-type': 'dot1q'
….
}
]

Example 2 : Incorrect—"untag" appears in more than one entry

instance-list: [
{ 'svc-instance': 5001,
'encap-type': 'untag'
}
{ 'svc-instance': 5002,
'encap-type': 'untag'
}
{ 'svc-instance': 5003,
'encap-type': 'dot1q'
….
}
]

vlan-id

number

Mandatory if encap-type is "dot1q"

(sub-property of svc-instance-list)

VLAN ID. The number must be unique under the interface.

Range: 1 to 4094

bridge-id

integer

Optional

bridge-domain-ID

Range: 1 to 4096

enabled

boolean

Optional

"true": Enable the interface

If this property is not present, the default behavior is to enable.

JSON Representation: Interface Schema

{
"kind": "object#l2interface",
"if-name": "{string}",
"description": "{string}",
"svc-instance-list":
[
{
"svc-instance": {number},
"encap-type": "{string}",
"vlan-id": {number},
"bridge-id": {number}
},
],
"enabled": {boolan}
}
 

Properties: L2 Interface State Schema

Applies to L2 interface APIs: /api/v1/l2interfaces/{if-id}/state

Property
Type
Required for POST and PUT
Description

kind

string

Not Applicable

Object type

if-name

string

Mandatory

Ethernet interface name

Example: gigabitethenet3

enabled

boolean

Mandatory

"true": Enable the interface

"false": Disable the interface

JSON Representation: Interface State Schema

{
"kind": "object#l2interface-state
"if-name": "{string}",
"enabled": {boolean}
}
 

Create an L2 Interface

Resource URI

Verb
URI

POST

/api/v1/l2interfaces

Example

JSON Request

POST /api/v1/l2interfaces
Content-Type: application/json
Accept: application/json
 
{
"if-name": "gigabitethernet2",
"svc-instance-list":
[
{
"svc-instance": 1001,
"encap-type": "dot1q",
"vlan-id": 4001,
},
{
"svc-instance": 1002,
"encap-type": "dot1q",
"vlan-id": 4002,
}
],
"enabled": true
}
 

JSON Response

201 Created
Location: https://host/api/v1/l2interfaces/GigabitEthernet2
 

Retrieve All L2 Interfaces

Resource URI

Verb
URI

GET

/api/v1/l2interfaces

Example

JSON Request

GET /api/v1/l2interfaces
Accept: application/json
 

JSON Response

200 ok
Content-Type: application/json
 
{
"kind": "collection#l2interface"
"items":
[
{
"kind": "object#l2interface",
"if-name": "gigabitethernet2",
"svc-instance-list":
[
{
"svc-instance": 1001,
"encap-type": "dot1q",
"vlan-id": 4001,
},
{
"svc-instance": 1002,
"encap-type": "dot1q",
"vlan-id": 4002,
}
],
"enabled": true
},
{
"kind": "object#l2interface",
"if-name": "gigabitethernet4",
"svc-instance-list":
[
{
"svc-instance": 2001,
"encap-type": "dot1q",
"vlan-id": 5001,
},
],
"enabled": false
},
]
}
 

Modify an L2 Interface

Resource URI

Verb
URI

PUT

/api/v1/l2interfaces/{if-id}

Example

JSON Request

PUT /api/v1/l2interfaces/gigabitethernet2
Content-Type: application/json
Accept: application/json
 
{
"if-name": "gigabitethernet2",
"svc-instance-list":
[
{
"svc-instance": 1001,
"encap-type": "dot1q",
"vlan-id": 4001,
},
{
"svc-instance": 1002,
"encap-type": "dot1q",
"vlan-id": 4002,
}
]
}
 

JSON Response

204 No Content
 

Retrieve an L2 Interface

Resource URI

Verb
URI

GET

/api/v1/l2interfaces/{if-id}

Example

JSON Request

GET /api/v1/l2interfaces/gigabitethernet2
Accept: application/json
 

JSON Response

200 ok
Content-Type: application/json
 
{
"kind": "object#l2interface",
"if-name": "gigabitethernet2",
"svc-instance-list":
[
{
"svc-instance": 1001,
"encap-type": "dot1q",
"vlan-id": 4001,
},
{
"svc-instance": 1002,
"encap-type": "dot1q",
"vlan-id": 4002,
}
],
"enabled": true
}
 

Delete an L2 Interface

Resource URI

Verb
URI

DELETE

/api/v1/l2interfaces/{if-id}

Example

JSON Request

DELETE /api/v1/l2interfaces/gigabitethernet2
 

JSON Response

204 No Content
 

Modify State of an L2 Interface

Resource URI

Verb
URI

PUT

/api/v1/l2interfaces/{if-id}/state

Example

JSON Request

PUT /api/v1/l2interfaces/gigabitethernet2/state
Content-Type: application/json
Accept: application/json
 
{
"if-name": "gigabitethernet2",
"enabled": true
}
 

JSON Response

204 No Content
 

Retrieve an L2 Interface State

Resource URI

Verb
URI

PUT

/api/v1/l2interfaces/{if-id}/state

Example

JSON Request

GET /api/v1/l2interfaces/gigabitethernet2/state
Accept: application/json
 

JSON Response

200 OK
 
Content-Type: application/json
Accept: application/json
 
{
"kind": "object#l2interface-state"
"if-name": "gigabitethernet2",
"enabled": true
}
 

 

Was this Document Helpful?

FeedbackFeedback

Contact Cisco