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:
July 31, 2014

Chapter: Global Configuration Requirements

Global Configuration Requirements

Resource Summary for Global Configuration

 

HTTP Method
Resource
URL (BaseURL)
GET
POST
PUT
DELETE

Banner

/api/v1/global/banner

Y

N

Y

N

Host name

/api/v1/global/host-name

Y

N

Y

N

Domain name

/api/v1/global/domain-name

Y

N

Y

N

Local users

/api/v1/global/local-users

Y

Y

N

N

/api/v1/global/local-users/{username}

Y

Y

Y

Y

Logging

/api/v1/global/logging

Y

Y

N

N

/api/v1/global/logging/{ip-address}

N

N

N

Y

/api/v1/global/logging/{ip-address}_{transport}_{port}

Y

N

N

Y

Global running configuration

/api/v1/global/running-config

Y

N

Y

N

SNMP

/api/v1/global/snmp

Y

Y

N

N

/api/v1/global/snmp/{ip-address}

Y

N

N

Y

TACACS

/api/v1/global/tacacs

Y

Y

N

N

/api/v1/global/tacacs/{name}

Y

N

Y

Y

Syslog

/api/v1/global/syslog

Y

N

Y

N

Reload

/api/v1/global/reload

N

N

Y

N

Save configuration

/api/v1/global/save-config

N

N

Y

N

Save configuration

autosave timer

/api/v1/global/autosave-timer

Y

N

Y

N

IPv6

/api/v1/global/ipv6/routing

Y

N

Y

N

CLI commands

/api/v1/global/cli

N

N

Y

N

Banner Resource

History

 

Release
Modification

IOS XE 3.11

Introduced for the CSR1000V platform

IOS XE 3.14

Introduced for ASR1001-X and ASR1002-X platforms

Properties

 

Property
Type
Required for POST and PUT
Description

kind

string

Not applicable

Object type: “object#banner”

exec

string

Optional

Exec mode message

Providing an empty string cancels the property.

login

string

Optional

Login message

Providing an empty string cancels the property.

motd

string

Optional

Message of the Day

Providing an empty string cancels the property.

JSON Representation

{
"kind" : "object#banner",
"exec" : "{string}",
"login" : "{string}",
"motd" : "{string}"
}

Retrieve Banner

Resource URI

 

Verb
URI

GET

/api/v1/global/banner

Example

JSON Request

GET /api/v1/global/banner
Accept: application/json

JSON Response

200 OK
Content-Type: application/json
{
"kind" : "object#banner"
"exec" : "{string}",
"login": "{string}",
"motd" : "{string}"
}

Modify Banner

Resource URI

 

Verb
URI

PUT

/api/v1/global/banner

Example

JSON Request

PUT /api/v1/global/banner
Content-Type: application/json
 
{
"exec" : "{string}",
"login": "{string}",
"motd" : "{string}"
}

JSON Response

204 No Content

Hostname Resource

The hostname resource represents the global configuration hostname property.

History

 

Release
Modification

IOS XE 3.10

Introduced for the CSR1000V platform

IOS XE 3.14

Introduced for ASR1001-X and ASR1002-X platforms

Properties

 

Property
Type
Required for POST and PUT
Description

kind

string

Not applicable

Object type. Always “object#hostname”

host-name

string

Mandatory

router name

Retrieve Device Hostname

Resource URI

 

Verb
URI

GET

/api/v1/global/host-name

Example

JSON Request

GET /api/v1/global/host-name
Accept: application/json

JSON Response

200 Ok
 
Content-Type: application/json
 
{
"kind" : "object#host-name",
"host-name": "{string}"
}

Modify Device Hostname

Resource URI

 

Verb
URI

PUT

/api/v1/global/host-name

Example

JSON Request

PUT /api/v1/global/host-name
 
Content-Type: application/json
Accept: application/json
 
{
"host-name": "eng-router"
}

JSON Response

200 Ok
 
Content-Type: application/json
 
{
"host-name": "eng-router"
}

JSON Response with no Response Body

204 No Content

Domain Name Resource

Represents the domain name property of the global configuration.

History

 

Release
Modification

IOS XE 3.10

Introduced for the CSR1000V platform

IOS XE 3.14

Introduced for ASR1001-X and ASR1002-X platforms

Properties

 

Property
Type
Description

kind

string

Object type. Always “object#domain-name”

domain-name

string

Domain name

Retrieve Domain Name

Resource URI

 

Verb
URI

GET

/api/v1/global/domain-name

Example

JSON Request

GET /api/v1/global/domain-name
Accept: application/json

JSON Response

200 Ok
 
Content-Type: application/json
{
"kind": "object#domain-name",
"domain-name": "cisco.com"
}

Modify Domain Name

Resource URI

 

Verb
URI

PUT

/api/v1/global/domain-name

Example

JSON Request

PUT /api/v1/global/domain-name
Content-Type: application/json
Accept: application/json
 
{
"domain-name": cisco.com
}

JSON Response

204 No Content

Users Resource

Users resource represents the collection of local users who are allowed to access the device.

History

 

Release
Modification

IOS XE 3.10

Introduced for the CSR1000V platform

IOS XE 3.11

Added pw-type property

IOS XE 3.14

Introduced for ASR1001-X and ASR1002-X platforms

Properties

 

Property
Type
Required for POST and PUT
Description

kind

string

Not applicable

Object type. Has fixed value “object#local-user”

username

string

Mandatory

Name of the user. Once created, cannot be modified.

password

string

Optional

Password.

privilege

number

Optional

Privilege level 0-15.

pw-type

number

Optional

IOS password type. Only type 0 and 7 are supported.

For a cleartext password, this argument is either 0 or optional.

Note : Because only type 0 and 7 are supported, switching from other IOS password types may not be possible. Those credentials may need to be deleted first, and new credentials created.

JSON Representation

{
"kind" : "object#local-user"
"username" : "cisco",
"password" : "ladf3434d",
"pw-type" : 7,
"privilege" : "15"
}

Create User Name

Resource URI

 

Verb
URI

POST

/api/v1/global/local-users

Example

JSON Request

POST /api/v1/global/local-users
Accept: application/json
 
Content-Type: application/json
 
{
"username": "jtod",
"password" : "re1st2",
"pw-type" : 7,
"privilege": 15
}

JSON Response

201 Created
Location: http://host/api/v1/global/local-users/jtod

Retrieve User Name or Password

Resource URI

 

Verb
URI

GET

/api/v1/global/local-users/{user-name}

Example

JSON Request

GET /api/v1/global/local-users/cisco
Accept: application/json
 

JSON Response

200 OK
Content-Type: application/json
 
{
"kind" : "object#local-user"
"username" : "cisco",
"password" : "1adf3434d",
"pw-type" : 7,
"privilege": 15
}
 

Retrieve All User Names

Resource URI

 

Verb
URI

GET

/api/v1/global/local-users

Properties for Retrieve All

 

Property
Type
Description

kind

string

Object type. Has fixed value “collection#local-user”

users

string

Array of user objects.

Example

JSON Request

GET /api/v1/global/local-users
Accept: application/json

JSON Response

200 OK
 
Content-Type: application/json
 
{
"kind": "collection#local-user"
"users": [
{
"kind" : "object#local-user",
"username" : "jtod",
"pw-type" : 7,
"privilege": 15
},
{
"kind": "object#local-user",
"username" : "marym",
"pw-type" : 7,
"privilege": 7
}
]
}
 

Modify User Attributes

Resource URI

 

Verb
URI

PUT

/api/v1/global/local-users/{user-name}

Example

JSON Request

PUT /api/v1/global/local-users/cisco
Content-Type: application/json
 
{
"username" : "cisco",
"password" : "ladf3434d",
"pw-type" : 7,
"privilege" : 15
}
 

JSON Response

204 No Content

Delete a User Name

Resource URI

 

Verb
URI

DELETE

/api/v1/global/local-users/{user-name}

Example

JSON Request

DELETE /api/v1/global/local-users/marym

JSON Response

204 No Content

Logging Resource

History

 

Release
Modification

IOS XE 3.11

Introduced for the CSR1000V platform

IOS XE 3.14

Introduced for ASR1001-X and ASR1002-X platforms

Properties

 

Property
Type
Required for POST and PUT
Description

kind

string

Not applicable

Object type. “object#logging”

ip-address

string

Mandatory

IP Address of the logging host

transport

string

Optional

Object type. “object#logging”

port

string

Optional

port of the logging host

JSON Representation

{
"kind" : "object#logging",
"ip-address" : "1.1.1.1",
"transport" : "udp",
"port" : 514
}

Create a Logging Object

Example

JSON Request

POST /api/v1/global/logging
Content-Type: application/json
 
{
"ip-address": "10.1.1.1",
"transport": "tcp",
"port": 1024
}

JSON Response

201 Created
Location: https://host/api/v1/global/logging/10.1.1.1_tcp_1024

Retrieve a Logging Object

Example

JSON Request

GET /api/v1/global/logging/10.1.1.1
Accept: application/json

JSON Response

200 OK
Content-Type: application/json
 
{
"kind" : "object#logging",
"ip-address" : "10.1.1.1",
"transport" : "udp",
"port" : 514
}

Retrieve All Logging Objects

Properties

 

Property
Type
Required for POST and PUT
Description

kind

string

Not applicable

Object type. Always “collection#logging”

items

array

Mandatory

Array of object#logging

 

JSON Representation

{
"kind" : "collection#logging",
"items" : [ {object#logging} ]
}

Example

JSON Request

GET /api/v1/global/logging
Accept: application/json

JSON Response

200 OK
Content-Type: application/json
 
{
"kind" : "collection#logging",
"items" : [
{
"kind" : "object#logging",
"ip-address" : "10.1.1.1",
"transport" : "udp",
"port" : 514
},
{
"kind" : "object#logging",
"ip-address" : "10.1.1.2",
"transport" : "tcp",
"port" : 1024
}
}

Deleting a Logging Object

Example

JSON Request

DELETE /api/v1/global/logging/10.1.1.1

JSON Response

204 No Content

Running-Config Resource

The Running-Config resource represents the Cisco IOS running configuration. Using this operation, you invoke a PUT operation by passing the snapshot of the running configuration as the request body.

Note There is no JSON representation for this resource. It supports only a text/plain representation that corresponds to IOS text configuration. GET and PUT operations correspond to Export and Import IOS actions.

History

 

Release
Modification

IOS XE 3.10

Introduced for the CSR1000V platform

IOS XE 3.14

Introduced for ASR1001-X and ASR1002-X platforms

Retrieving or Exporting the Running Configuration

Resource URI

 

Verb
URI

GET

/api/v1/global/running-config

Example

JSON Request

GET /api/v1/global/running-config
Accept: application/json

JSON Response

200 OK
 
Content-Type: "text/plain"
 
 
!
! Last configuration change at 16:07:15 IST Fri Jun 15 2012
version 15.2
service timestamps debug datetime msec
service timestamps log datetime msec
no service password-encryption
!
hostname Router
!

Import the Running Configuration

Note The running configuration file cannot contain a self-signed certificate. If the CSR already has a self-signed certificate, then the configuration file being imported cannot have a self-signed certificate unless the self-signed certificate is removed from CSR first.

Resource URI

 

Verb
URI

PUT

/api/v1/global/running-config

Example

JSON Request

PUT /api/v1/global/running-config
 
Content-Type: "text/plain"
 
 
!
! Last configuration change at 16:07:15 IST Fri Jun 15 2012
version 15.2
service timestamps debug datetime msec
service timestamps log datetime msec
no service password-encryption
!
hostname Router
!
 

JSON Response

204 No Content

SNMP Server Resource

History

 

Release
Modification

IOS XE 3.11

Introduced for the CSR1000V platform

IOS XE 3.14

Introduced for ASR1001-X and ASR1002-X platforms

Properties

 

Property
Type
Required for POST and PUT
Description

kind

string

Not applicable

Object type. “object#snmp”

ip-address

string

Mandatory

IP Address of the SNMP server

community-string

string

Mandatory

SNMPv1/v2 community-string or SNMPv3 user name

JSON Representation

{
"kind" : "object#snmp",
"ip-address" : {string},
"community-string" : {string}
}

Create SNMP Object

Example

JSON Request

POST /api/v1/global/snmp
Content-Type: application/json
 
{
"ip-address" : "10.1.1.1",
"community-string" : "cisco123"
}
 

JSON Response

201 Created
Location: https://host/api/v1/global/snmp/10.1.1.1_cisco123

Retrieve SNMP Object

Example

JSON Request

GET /api/v1/global/snmp/10.1.1.1_abc123
Accept: application/json

JSON Response

200 OK
Content-Type: application/json
 
{
"kind" : "object#snmp",
"ip-address" : "10.1.1.1",
"community-string" : "abc123"
}

Retrieve All SNMP Objects

Properties for Retrieve All

 

Property
Type
Description

kind

string

Object type. Always “collection#snmp”

items

array

Array of object#snmp

JSON Representation

{
"kind" : "collection#snmp",
"items" : [ {object#snmp} ]
}

Example

JSON Request

GET /api/v1/global/snmp
Accept: application/json

JSON Response

200 OK
Content-Type: application/json
 
{
"kind" : "collection#snmp",
"items" : [
{
"kind": "object#snmp",
"ip-address": "10.1.1.1",
"community-string": "abc123"
},
{
"kind": "object#snmp",
"ip-address": "10.1.1.2",
"community-string": "abc123"
}
}

Delete SNMP Object

Example

JSON Request

DELETE /api/v1/global/snmp/10.1.1.1_abc123
 

JSON Response

204 No Content

TACACS Server Resource

History

 

Release
Modification

IOS XE 3.11

Introduced for the CSR1000V platform

IOS XE 3.14

Introduced for ASR1001-X and ASR1002-X platforms

Properties

 

Property
Type
Required for POST and PUT
Description

kind

string

Not applicable

Object type. “object#tacacs”

name

string

Mandatory

Name of TACAS server

ip-address

string

Mandatory

IP Address of the TACACS server

key

String

Optional

key

Note : This key will not be returned in the GET API for security reasons.

JSON Representation

{
"kind" : "object#tacacs",
"name" : {string},
"ip-address": {string},
"key": {string}
}
 

Create TACACS Server

Example

JSON Request

POST /api/v1/global/tacacs
Content-Type: application/json
 
{
"name" : "primary",
"ip-address" : "10.1.1.1",
"key" : "cisco123"
}
 

JSON Response

201 Created
Location: https://host/api/v1/global/tacacs/primary
 

Retrieve TACACS Server

Example

JSON Request

GET /api/v1/global/tacacs/primary
Accept: application/json

JSON Response

200 OK
Content-Type: application/json
 
{
"kind" : "object#tacacs",
"name" : "primary",
"ip-address": "10.1.1.1"
}

Retrieve All TACACS Servers

Properties for Retrieve All

 

Property
Type
Description

kind

string

Object type. Always “collection#tacacs”

items

array

Array of object#tacacs

JSON Representation for Retrieve All

{
"kind" : "collection#tacacs",
"items" : [ {object#tacacs} ]
}

Example

JSON Request

GET /api/v1/global/tacacs
Accept: application/json

JSON Re sponse

200 OK
Content-Type: application/json
 
{
"kind" : "collection#tacacs",
"items" : [
{
"kind" : "object#tacacs",
"name" : "primary",
"ip-address": "10.1.1.1"
},
{
"kind" : "object#tacacs",
"name" : "secondary",
"ip-address": "10.1.1.2"
}
]
}
 

Modify TACACS Server

Example

JSON Request

PUT /api/v1/global/tacacs/primary
Content-Type: application/json
 
{
"ip-address" : "10.1.1.1",
"key" : "cisco123"
}

JSON Re sponse

204 No Content

Delete TACACS Server

Example

JSON Request

DELETE /api/v1/global/tacacs/primary

JSON Re sponse

204 No Content
 

Syslog Resource

This resource is used to retrieve the CSR logs. The Properties table describes the fields in the show processes cpu output.

History

 

Release
Modification

IOS XE 3.10

Introduced for the CSR1000V platform

IOS XE 3.14

Introduced for ASR1001-X and ASR1002-X platforms

Properties

 

Field
Type
Description

kind

string

Must be “object#syslog-buffer”

messages

string

Syslog messages

JSON Representation

{
"kind": "object#syslog-buffer",
"messages": "{string}"
}

Retrieve the Syslog

Example

JSON Request

GET /api/v1/global/syslog
 
Accept: application/json

JSON Response

200 OK
 
Content-Type: application/json
 
{
"kind" : "object#syslog-buffer",
"messages": "{string}"
}

Reload Resource

Reloads/reboots the router after a specified interval, up to 60 minutes.

History

 

Release
Modification

IOS XE 3.12

Introduced for the CSR1000V platform

IOS XE 3.14

Introduced for ASR1001-X and ASR1002-X platforms

Properties

 

Property
Type
Required for POST and PUT
Description

minutes

number

Mandatory

Reloads after the specified interval in minutes.

Range: 0 to 60

A value of 0 indicates an immediate reload and will terminate the REST HTTP session.

JSON Representation

{
"minutes": {number}
}
 

Reload Router

Resource URI

 

Verb
URI

PUT

/api/v1/global/reload

Example

JSON Request

PUT /api/v1/global/reload
Content-Type: application/json
 
{
"minutes" : 5
}

JSON Response

204 No Content
 

Saving the REST API Configuration

This resource saves the REST API configuration file.

History

 

Release
Modification

IOS XE 3.13

Introduced for the CSR1000V platform

IOS XE 3.14

Introduced for ASR1001-X and ASR1002-X platforms

The following API is not supported:

/api/v1/global/autosave-timer

Saving the REST API configuration file (IOS write memory CLI command) introduces a delay of a few seconds, depending on the size of the configuration file. To reduce the impact that the write memory command has on the REST API performance, the configuration is saved at a fixed time interval.

  • save-config API

Save the REST API configuration file. See Save REST API Configuration File.

  • autosave-timer API

Configure or retrieve the autosave interval. See Configure the Autosave Timer Interval.

The time interval is also configurable using a new CLI based on the restful-api CLI command.

Save REST API Configuration File

Resource URI

 

Verb
URI

PUT

/api/v1/global/save-config

Example

JSON Request

PUT /api/v1/global/save-config
Content-Type: application/json
 

JSON Response

204 No Content
 

Configure the Autosave Timer Interval

Properties

 

Property
Type
Required for POST and PUT
Description

timeout

integer

Mandatory

Interval setting from 30 to 300 seconds

JSON Representation

{
"timeout": {integer}
}

Resource URI

 

Verb
URI

PUT

/api/v1/global/autosave-timer

See Historyfor platform limitations.

Example

JSON Request

PUT /api/v1/global/autosave-timer
Content-Type: application/json
 
{
"timeout": 30
}
 

JSON Response

204 No Content

 

Retrieve the Autosave Timer Interval

Resource URI

 

Verb
URI

GET

/api/v1/global/autosave-timer

See Historyfor platform limitations.

Example

JSON Request

GET /api/v1/global/autosave-timer
 

JSON Response

200 ok
 
Content-type: application/json
 
{ "timeout" : 30}
 

 

IPv6 Resource

History

 

Release
Modification

IOS XE 3.16

Introduced for the CSR1000V platform

Properties

 

Property
Type
Required for POST and PUT
Description

kind

string

Not applicable

Object type: "object#ipv6-routing"

unicast

boolean

Optional

Enables the forwarding of IPv6 unicast datagrams

multicast

boolean

Optional

Enables the forwarding of IPv6 multicast datagrams

JSON Representation

{
"kind": "object#ipv6-routing",
"unicast": {boolean},
"multicast": {boolean}
}
 

Support for Any CLI

This resource can be used to configure any CLI through the REST API.

History

 

Release
Modification

IOS XE 3.16

Introduced for the CSR1000V platform

Properties

 

Property
Type
Required for POST and PUT
Description

config

string

Optional

CLI to be applied in the config mode

exec

string

Optional

CLI to be applied in the exec mode

show

string

Optional

CLI to be run to show the results

JSON Representation

{
"config":"string",
"exec":"string",
"show":"string"
}
 

Configure a CLI in "config" Mode

Resource URI

 

Verb
URI

PUT

/api/v1/global/cli

Example

JSON Request

PUT /api/v1/global/cli
Content-Type: application/json
 
{
"config": "interface lisp0"
}
 

JSON Response

204 No Content
 

Configure Multiple CLIs in "config" Mode

Separate multiple CLIs with \n.

Resource URI

 

Verb
URI

PUT

/api/v1/global/cli

Example

JSON Request

PUT /api/v1/global/cli
Content-Type: application/json
 
{
"config": "crypto ssl proposal SSL_PROP \n protection rsa-aes128-sha1"
}
 

JSON Response

204 No Content
 

Configure a CLI to Show Output

Resource URI

 

Verb
URI

PUT

/api/v1/global/cli

Example

JSON Request

PUT /api/v1/global/cli
Content-Type: application/json
 
{
"show": " privilege"
}
 

JSON Response

200 OK
Content-Type: application/json
 
{
"kind": "object# cli-results",
"results": "Current privilege level is 15"
}
 

Configure Multiple CLIs in "exec" Mode

Separate multiple CLIs with \n.

Resource URI

 

Verb
URI

PUT

/api/v1/global/cli

Example

JSON Request

PUT /api/v1/global/cli
Content-Type: application/json
 
{
"exec": " ping 1.1.1.1"
}
 

JSON Response

200 OK
Content-Type: application/json
 
{
"kind": "object# cli-results",
"results": "Type escape sequence to abort.\nSending 5, 100-byte ICMP Echos to 1.1.1.1, timeout is 2 seconds:\n.....\nSuccess rate is 0 percent (0/5)"
}
 

 

Was this Document Helpful?

FeedbackFeedback

Contact Cisco