1 Host APIs

sjurcak · ‎10-09-2017

Cisco Software Manager Server

API Guide

This document describes the programmatic interfaces, RESTful APIs, which are supported by Cisco Software Manager Server (CSM Server).

Overview

CSM Server supports a set of finite RESTful APIs. The first step to use these APIs is to acquire an access token using a valid CSM Server username and password. The access token has a time limit of an hour. Once the time expires, the external application must acquire a new access token. Below are examples of how an access token can be acquired.

Example of using curl:

curl -u <username>:<password> http://localhost:5000/api/v1/token

Example of using Python requests (http://docs.python-requests.org/en/master/)

import requests

requests.get("http://localhost:5000/api/v1/token", auth=(<username>, <password>))

Sample JSON Response:

{

"token": "eyJhbGciOiJIUzI1NiIsImV4cCI6MTQzMzE4ODcyNiwiaWF0IjoxNDMzMTg4M"

}

Once an access token is acquired, it will be used as a username for the RESTful APIs. The password should use the string "unused". See the Python Example in section Create Hosts.

The APIs in this document use JSON format as input and output. Some implementations require Content-Type: application/json be set in the HTTP header to work properly.

Table of Contents

2.1 Create Jump Host 7

2.2 Get Jump Hosts. 8

2.3 Delete Jump Hosts. 9

3 Region APIs. 10

3.1 Create Region. 10

3.2 Get Regions. 11

3.3 Delete Region. 12

4 Server Repository APIs. 12

4.1 Create Server Repositories. 12

4.2 Get Server Repositories. 14

4.3 Delete Server Repositories. 15

5 Custom Command Profile APIs. 16

5.1 Create Custom Command Profiles. 16

5.2 Get Custom Command Profiles. 17

5.3 Delete Custom Command Profiles. 18

6 CCO APIs. 18

6.1 Get CCO Catalog. 18

6.2 Get CCO Software. 19

6.3 Get CCO Software Entry. 21

6.4 Get Optimized Software. 22

7 Schedule Installation APIs. 23

7.1 Install Action: Pre-Upgrade, Post-Upgrade, Commit 25

7.2 Install Action: Add. 26

7.3 Install Action: Activate, Remove, Deactivate. 27

7.4 Install Action: FPD-Upgrade. 28

7.5 Get Install Jobs. 28

7.6 Delete Install Jobs. 30

7.7 Get Logs. 31

RESTful APIs

In the Sample Requests in each section, the URL contains the string "localhost:5000". When building your URLs, "localhost" should be replaced with the name or IP address of the server running CSM Server.

1 Host APIs

1.1 Create Hosts

Creates hosts on CSM Server. Multiple hosts can be created with one request. If an existing host is specified, it will cause an update in the CSM database. If updating, only the hostname and the new parameters and values are required.

Request Parameters:

Parameter	Required	Type	Length	Description
hostname	Yes	string	50	The hostname of the managed host to be created.
region	Yes	string	100	The region the managed host belongs to. The region must exist in the CSM database.
location	No	string	100	The physical location of the host.
roles	No	list	N/A	The roles of the managed host. Multiple roles may be specified as additional elements in the list.
software_profile	No	string	100	The software profile that the host is associated with.
connection_type	Yes	string	N/A	The connection method to the managed host. It must be either "telnet" or "ssh".
ts_or_ip	Yes	list	N/A	The Terminal Server IP or management IP to the managed host. Multiple multiple IPs (active and standby) may be specified as additional elements in the list.
port_number	No	list	N/A	The port number to connect to the managed host. Multiple ports (active and standby) may be specified as additional elements in the list.
username	No	string	50	The username to the managed host.
password	No	string	50	The password to the managed host.
enable_password	No	string	100	The enable password of the host.
jump_host	No	string	100	The jump host name for CSM to log into in order to connect to the managed host. The jump host must exist in the CSM database.

Sample Request:

POST:
http://localhost:5000/api/v1/hosts

Single Host Example:

Multiple Host Example:

BODY:

[{ "hostname": "My Host 1",
  "region": "SJ Labs",
  "roles": ["PE"],
  "connection_type": "telnet",
  "ts_or_ip": ["172.28.98.2"],
  "port_number": ["2017","2018"], "username": "cisco",
  "password": "cisco"}]

BODY:

[{

"hostname": "My Host 1",

"region": "SJ Labs",

"roles": ["PE"],

"connection_type": "telnet",

"ts_or_ip": ["172.28.98.2"],

"port_number": ["2017","2018"],

"username": "cisco",

"password": "cisco"

},

{

"hostname": "My Host 2",

"region": "SJ Labs",

"roles": ["PE"],

"connection_type": "telnet",

"ts_or_ip": ["172.28.98.3"],

"username": "cisco",

"password": "cisco"

}

]

Python Example:

import requestspayload = [
{"hostname": "My Host 1", "region": "SJ Labs", "roles": "PE", "connection_type": "telnet", "ts_or_ip": "172.28.98.2", "username": "cisco", "password": "cisco"},

{"hostname": "My Host 2", "region": "SJ Labs", "roles": "PE", "connection_type": "telnet", "ts_or_ip": "172.28.98.2",

"username": "cisco", "password": "cisco"},
]
response = requests.post("http://localhost:5000/api/v1/hosts",

auth=(token, "unused"), json=payload)

Sample Response:

{ "api_response": {
  "host_list": [{"status": "SUCCESS", "hostname": "My Host 1"},
                  {"status": "SUCCESS", "hostname": "My Host 2"}]
  }
}

Possible Error Codes:

HTTP Code	Possible Scenario
400	Bad Request; check that POST or GET is correct.
400	Bad input parameters—check that valid input was given.
401	Invalid credentials or expired token.
401	User does not have the required permissions.
207	Some operations in the request failed.

1.2 Get Hosts

Returns managed hosts specified by their region and family.

Request Parameters:

Parameter	Required	Type	Length	Description
hostname	No	string	100	The hostname of the host to query.
family	No	string	20	The family the managed hosts belong to. (e.g. ASR9K, CRS, NCS1K, NCS5K, NCS5500, NCS6K)
region	No	string	100	The region the managed hosts belong to.
page	No	int		The page number. Each page returns 1000 entries.

Sample Request:

GET:

Http://localhost:5000/api/v1/hosts

http://localhost:5000/api/v1/hosts?hostname=Host_1
http://localhost:5000/api/v1/hosts?region=SJ Labs
http://localhost:5000/api/v1/hosts?region=SJ Labs&page=2
http://localhost:5000/api/v1/hosts?region=SJ%20Labs&family=ASR9K

Sample Response:

{

"api_response": {

"host_list": [

{

"connection_type": "telnet",

"family": "ASR9K",

"chassis": "ASR-9006",

"os_type": "XR",

"ts_or_ip": ["10.122.54.101"],

"username": "cisco",

"hostname": "R1",

"jump_host": "",

"port_number": [],

"region": "RTP-SVS",

"roles": ["P"],

"software_platform": "ASR9K",

"software_version": "5.3.0",

"location": "building 20"

},

{

"connection_type": "telnet",

"family": "ASR9K",

"chassis": "ASR-9904",

"os_type": "eXR",

"ts_or_ip": ["10.48.32.235"],

"username": "iox",

"hostname": "R2",

"jump_host": "",

"port_number": [],

"region": "SJ Labs",

"roles": [],

"software_platform": "ASR9K-64",

"software_version": "6.1.0.06I",

"location": "building 20"

},

]

},

"current_page": 1,

"total_pages": 1

}

Possible Error Codes:

HTTP Code	Possible Scenario
400	Bad Request; check that POST or GET is correct.
	Unknown page number; there are fewer results than would require the number of pages input.
	Unknown region; the region provided does not exist in the database. Check that the name was input correctly.
401	Invalid credentials or expired token.
401	User does not have the required permissions.

1.3 Delete Host

Deletes a managed host.

Request Parameters:

Parameter	Required	Type	Length	Description
hostname	Yes	string	50	The hostname of the managed host to be deleted.

Sample Request:

DELETE:
http://localhost:5000/api/v1/hosts/<hostname>/delete

Sample Response:

{
"api_response": {"status": "SUCCESS", "hostname": "Host_1"}
}

Possible Error Codes:

HTTP Code	Possible Scenario
400	Server encountered an error.
401	Invalid credentials or expired token.
401	User does not have the required permissions.

2 Jump Host APIs

2.1 Create Jump Host

Creates jump hosts on CSM Server. Multiple jump hosts can be created with one request. If an existing jump host is specified, it will cause an update in the CSM database. If updating, only the hostname and the new parameters and values are required.

Request Parameters:

Parameter	Required	Type	Length	Description
hostname	Yes	string	100	The name of the jump host to be created.
connection_type	Yes	string	N/A	Accepted values are "telnet" and "ssh".
host_or_ip	Yes	string	50	Either the hostname of the server or the IP address.
port_number	No	string	10	Optional port number
username	No	string	50	Username for logging on to the host.
password	No	string	100	Password for logging on to the host.

Sample Request:

POST:
http://localhost:5000/api/v1/jump_hosts

BODY:

[{ "hostname": "Jump_Host_1", "connection_type": "telnet", "host_or_ip": "1.1.1.1", "port_number": 5000, "username": "root", "password": "root"

},

{

"hostname": "Jump_Host_2", "connection_type": "ssh", "host_or_ip": "my-server", "username": "root", "password": "root"

}]

Sample Response:

{ "api_response": {
"jump_host_list": [{"status": "SUCCESS", "hostname": "Jump_Host_1"},
{"status": "SUCCESS", "hostname": "Jump_Host_2"}]
}
}

Possible Error Codes:

HTTP Code	Possible Scenario
400	Bad Request; check that POST or GET is correct.
400	Bad input parameters—check that valid input was given.
401	Invalid credentials or expired token.
401	User does not have the required permissions.
207	Some operations in the request failed.

2.2 Get Jump Hosts

Returns jump hosts by page.

Parameter	Required	Type	Length	Description
hostname	No	string	100	The hostname of the jump host to query.

Sample Request:

GET:
http://localhost:5000/api/v1/jump_hosts

http://localhost:5000/api/v1/jump_hosts?hostname=Jump_Host_1

Sample Response:

{

"api_response": {

"jump_host_list": [

{

"hostname": "Jump_Host_1", "connection_type": "telnet", "name_or_ip": "1.1.1.1", "port": 23, "username": "root"

},

{

"hostname": "Jump_Host_2", "connection_type": "ssh", "name_or_ip": "my-server", "username": "root", "port": ""

}]

}

Possible Error Codes:

HTTP Code	Possible Scenario
400	Bad Request; check that POST or GET is correct.
	Unknown page number; there are fewer results than would require the number of pages input.
	Unknown region; the region provided does not exist in the database. Check that the name was input correctly.
401	Invalid credentials or expired token.
401	User does not have the required permissions.

2.3 Delete Jump Hosts

Deletes jump hosts on CSM Server.

Request Parameters:

Parameter	Required	Type	Length	Description
hostname	Yes	string	100	The name of the jump host to be deleted.

Sample Request:

DELETE:
http://localhost:5000/api/v1/jump_hosts/<hostname>/delete

Sample Response:

{ "api_response": {"status": "SUCCESS", "hostname": "Jump_Host_1"}
}

Possible Error Codes:

HTTP Code	Possible Scenario
400	Bad Request; check that DELETE is correct in the http request.
400	Bad input parameters—check that valid input was given.
401	Invalid credentials or expired token.
401	User does not have the required permissions.

3 Region APIs

3.1 Create Region

Creates regions on CSM Server. Multiple regions can be created with one request. If an existing region is specified, it will cause an update in the CSM database. If updating, only the region_name and the new parameters and values are required.

Request Parameters:

Parameter	Required	Type	Length	Description
region_name	Yes	string	100	The name of the region to be created.
server_repositories	No	list	N/A	A list of server repositories in the region. All server repositories must exist in the CSM database. If a region does not have any server repositories, all server repositories will be available to the region.

Sample Request:

POST:
http://localhost:5000/api/v1/regions

BODY:

[{ "region_name": "Region_1", "server_repositories": ["Repository1", "Repository2"]

},

{

"region_name": "Region_2"

}]

Sample Response:

{ "api_response": {
  "region_list": [{"status": "SUCCESS", "region_name": "Region_1"},
                   {"status": "SUCCESS", "region_name": "Region_2"}]
  }
}

Possible Error Codes:

HTTP Code	Possible Scenario
400	Bad Request; check that POST or GET is correct.
400	Bad input parameters—check that valid input was given.
401	Invalid credentials or expired token.
401	User does not have the required permissions.
207	Some operations in the request failed.

3.2 Get Regions

Parameter	Required	Type	Length	Description
region_name	No	string	100	The name of the region to query

Sample Request:

GET:
http://localhost:5000/api/v1/regions

http://localhost:5000/api/v1/regions?region_name=Region_1

Sample Response:

{

"api_response": {

"region_list": [

{

"region_name": "Region_1", "server_repositories": ["Repository1", "Repository2"]

},

{

"region_name": "Region_2",

"server_repositories": []

}

]

}

Possible Error Codes:

HTTP Code	Possible Scenario
400	Bad Request; check that POST or GET is correct.
400	Unknown region; the region provided does not exist in the database. Check that the name was input correctly.
401	Invalid credentials or expired token.
401	User does not have the required permissions.

3.3 Delete Region

Deletes regions on CSM Server. Only regions that have no hosts can be deleted.

Request Parameters:

Parameter	Required	Type	Length	Description
region_name	Yes	string	100	The name of the region to be deleted.

Sample Request:

DELETE:

http://localhost:5000/api/v1/regions/<region_name>/delete

Sample Response:

{ "api_response": {"status": "SUCCESS", "region_name": "Region_1"}
} OR { "api_response": { "status": "FAILED", "status_message": "Unable to locate region ‘Region_2’" }}

Possible Error Codes:

HTTP Code	Possible Scenario
400	Bad Request; check that DELETE is correct in the http request.
400	Bad input parameters—check that valid input was given.
401	Invalid credentials or expired token.
401	User does not have the required permissions.

4 Server Repository APIs

4.1 Create Server Repositories

Creates server repositories on CSM Server. Multiple server repositories can be created with one request. If an existing server repositories is specified, it will cause an update in the CSM database (server_type is not editable). If updating, only the hostname and the new parameters and values are required.

Request Parameters:

Parameter	Required	Type	Length	Description
hostname	Yes	string	100	The name of the server repository to be created.
server_type	Yes	string	20	Accepted values are "TFTP", "FTP", "SFTP", “SCP”, and "LOCAL".

Additional Parameters for Respective Server Types:

server_type	Parameter	Required	Type	Length	Description
TFTP	tftp_server_path	Yes	string	100
	file_directory	Yes	string	100	The absolute file path.
	vrf	No	string	100	Specify the VRF used for TFTP if any.
FTP	server_address	Yes	string	100
	home_directory	Yes	string	100	The absolute file path.
	vrf	No	string	100	Specify the VRF used for FTP if any.
	username	No	string	100
	password	No	string	100
SFTP	server_address	Yes	string	100
	home_directory	Yes	string	100	The absolute file path.
	username	No	string	100
	password	No	string	100
SCP	server_address	Yes	string	100
	home_directory	Yes	string	100	The absolute file path.
	username	No	string	100
	password	No	string	100
	destination_on_host	Yes	string	100	Example: disk0:
LOCAL	device_path	Yes	string	100	Example: disk0:

Sample Request:

POST:
http://localhost:5000/api/v1/server_repositories

BODY:

[{ "hostname": "Repository_1", "server_type": "TFTP", "tftp_server_path": "223.255.254.245", "file_directory": "/auto/tftp-sjc-users1", "vrf": "Mgmt-intf"},{ "hostname": "Repository_2", "server_type": "FTP", "server_address": "172.27.153.150", "home_directory": "/tftpboot", "vrf": "Mgmt-intf", "username": "root", "password": "root"},{ "hostname": "Repository_3", "server_type": "SFTP", "server_address": "nb-server3", "home_directory": "/auto/tftp-vista", "username": "root", "password": "root"},{ "hostname": "Repository_4", "server_type": "LOCAL", "device_path": "disk0:",}]

Sample Response:

{ "api_response": { "server_repository_list": [ {"status": "SUCCESS", "hostname": "Repository_1"}, {"status": "SUCCESS", "hostname": "Repository_2"}, {"status": "SUCCESS", "hostname": "Repository_3"}, {"status": "SUCCESS", "hostname": "Repository_4"}, {"status": "SUCCESS", "hostname": "Repository_5"}] }}

Possible Error Codes:

HTTP Code	Possible Scenario
400	Bad Request; check that POST or GET is correct.
400	Bad input parameters—check that valid input was given.
401	Invalid credentials or expired token.
401	User does not have the required permissions.
207	Some operations in the request failed.

4.2 Get Server Repositories

Returns server repositories by page.

Parameter	Required	Type	Length	Description
hostname	No	string	100	The hostname of the server repository to query.

Sample Request:

GET:
http://localhost:5000/api/v1/server_repositories

http://localhost:5000/api/v1/server_repositories?hostname=Repository_1

Sample Response:

{

"api_response": {

"server_repository_list": [

{

"hostname": "Repository_1", "server_url": "1.1.1.1", "home_directory": "/home", "server_type": "TFTP", "home_directory": "/home", "vrf": ""

},

{

"hostname": "Repository_2", "server_url": "2.2.2.2", "home_directory": "/", "server_type": "FTP", "vrf": "" } ]

}

Possible Error Codes:

HTTP Code	Possible Scenario
400	Bad Request; check that POST or GET is correct.
	Unknown page number; there are fewer results than would require the number of pages input.
	Unknown region; the region provided does not exist in the database. Check that the name was input correctly.
401	Invalid credentials or expired token.
401	User does not have the required permissions.

4.3 Delete Server Repositories

Deletes server repositories on CSM Server.

Request Parameters:

Parameter	Required	Type	Length	Description
hostname	Yes	string	100	The name of the server repository to be deleted.

Sample Request:

DELETE:
http://localhost:5000/api/v1/server_repositories/<hostname>/delete

Sample Response:

{ "api_response": {"status": "SUCCESS", "hostname": "Repository_1"}
}

Possible Error Codes:

HTTP Code	Possible Scenario
400	Bad Request; check that DELETE is correct in the http request.
400	Bad input parameters—check that valid input was given.
401	Invalid credentials or expired token.
401	User does not have the required permissions.

5 Custom Command Profile APIs

5.1 Create Custom Command Profiles

Creates custom command profiles on CSM Server. Multiple profiles can be created with one request. If an existing profile is specified, it will cause an update in the CSM database.

Request Parameters:

Parameter	Required	Type	Length	Description
profile_name	Yes	string	100	The name of the custom command profile to be created.
command_list	Yes	list	N/A	A list of valid CLI commands.

Sample Request:

POST:
http://localhost:5000/api/v1/custom_command_profiles

BODY:

[{ "profile_name": "Profile_1", "command_list": ["show platform", "show install inactive"] }, { "profile_name": "Profile_2", "command_list": ["show platform"] }]

Sample Response:

{ "api_response": { "custom_command_profile_list": [ {"status": "SUCCESS", "profile_name": "Profile_1"}, {"status": "SUCCESS", "profile_name": "Profile_2"}] }}

Possible Error Codes:

HTTP Code	Possible Scenario
400	Bad Request; check that POST or GET is correct.
400	Bad input parameters—check that valid input was given.
401	Invalid credentials or expired token.
401	User does not have the required permissions.
207	Some operations in the request failed.

5.2 Get Custom Command Profiles

Returns custom command profiles.

Parameter	Required	Type	Length	Description
profile_name	No	string	100	The name of the custom command profile to query.

Sample Request:

GET:
http://localhost:5000/api/v1/custom_command_profiles

http://localhost:5000/api/v1/custom_command_profiles?profile_name=Profile_1

Sample Response:

{

"api_response": {

"custom_command_profile_list": [

{

"profile_name": "Profile_1", "command_list": ["show platform", "show install inactive"]

},

{

"profile_name": "Profile_2", "command_list": ["show platform"] }] }

}

Possible Error Codes:

HTTP Code	Possible Scenario
400	Bad Request; check that POST or GET is correct.
400	Unknown region; the region provided does not exist in the database. Check that the name was input correctly.
401	Invalid credentials or expired token.
401	User does not have the required permissions.

5.3 Delete Custom Command Profiles

Deletes custom command profiles on CSM Server.

Request Parameters:

Parameter	Required	Type	Length	Description
profile_name	Yes	string	100	The name of the custom command profile to be deleted.

Sample Request:

DELETE:
http://localhost:5000/api/v1/custom_command_profiles/<profile_name>/delete

Sample Response:

{ "api_response": {"status": "SUCCESS", "profile_name": "Profile_1"}
}

Possible Error Codes:

HTTP Code	Possible Scenario
400	Bad Request; check that DELETE is correct in the http request.
400	Bad input parameters—check that valid input was given.
401	Invalid credentials or expired token.
401	User does not have the required permissions.

6 CCO APIs

6.1 Get CCO Catalog

Returns the platforms and releases that are displayed under the CCO menu. The platform and release can be used to retrieve software information in other CCO related APIs.

Request Parameters:

None

Sample Request:

GET:
http://localhost:5000/api/v1/cco/catalog

Sample Response:

{

"api_response": {

"asr9k_px": [

"6.0.0",

"5.3.3",

"5.3.2",

"5.3.1"

],

"crs_px": [

"5.3.3",

"5.3.2"

],

"ncs6k": [

"5.2.5",

"5.2.4",

"5.2.3"

],

"ncs6k_sysadmin": [

"5.2.5",

"5.2.4",

"5.2.3"

]

}

Possible Error Codes:

HTTP Code	Possible Scenario
401	Invalid credentials or expired token.

6.2 Get CCO Software

Returns all software information for a particular release and platform since a particular date (i.e. CCO posted date).

Request Parameters:

Parameter	Required	Type	Length	Description
platform	Yes	string	N/A	The platform that is supported by the CCO software catalog, as shown in the get catalog response.
release	Yes	string	N/A	The release that is supported by the CCO software catalog, as shown in the get catalog response.
date	No	string	N/A	The software (SMU/Service Pack) was posted since this date. The date should be in mm-dd-yyyy format.
optimal	No	string	N/A	By default, only optimal software is returned. If this value is "false", it will return all posted software.

Sample Request:

GET:
http://localhost:5000/api/v1/cco/software?platform=asr9k_px&release=5.3.3

http://localhost:5000/api/v1/cco/software?platform=asr9k_px&release=5.3.3&date=12-20-2015

http://localhost:5000/api/v1/cco/software?platform=asr9k_px&release=5.3.3&date=12-20-2015&optimal=false

Sample Response:

{

"api_response": {

"software_list": [

{

"impact": "Needs Reboot",

"package_bundles": "asr9k-mini-px",

"compressed_image_size": "4261807",

"posted_date": "04/19/2016 17:14:11 PDT",

"composite_DDTS": [],

"functional_areas": ["QOS"],

"superseded_by": [],

"supersedes": [],

"name": ["asr9k-px-5.3.3.CSCux31992"],

"prerequisites": [],

"ddts": "CSCux31992",

"status": "Posted",

"uncompressed_image_size": "18851717",

"type": "Recommended",

"id": "AA11103",

"description": "nV Edge IRL flap by Bay0 MPA reload, even if we change timeout of UDLD"

},

...

]

}

Possible Error Codes:

HTTP Code	Possible Scenario
401	Invalid credentials or expired token.

6.3 Get CCO Software Entry

Returns information related to a specific software item by its name or ID (e.g. a SMU/Sevice Pack/Release Software)

Request Parameters:

Parameter	Required	Type	Length	Description
name_or_id	Yes	string	N/A	The software name or ID as defined (e.g. asr9k-p-4.2.3.CSCut30136 or AA09694).
platform	Yes	string	N/A	The platform that is supported by the CCO software catalog, as shown in the get catalog response.
release	Yes	string	N/A	The release that is supported by the CCO software catalog, as shown in the get catalog response.

Sample Request:

GET:
http://localhost:5000/api/v1/cco/software/<name_or_id>?platform=asr9k_px&release=5.3.3

Sample Response:

{

"api_response": {

"composite_DDTS": [],

"compressed_image_size": "113616329",

"ddts": "CSCuz05961",

"description": "Link Flaps : Adaptive FEC control algorithm not working in 4x10GE",

"functional_areas": ["ETHER"],

"id": "AA11308",

"impact": "Needs Reboot",

"name": "asr9k-px-5.3.3.CSCuz05961",

"package_bundles": ["asr9k-mini-px"],

"posted_date": "04/27/2016 21:39:38 PDT",

"prerequisites": ["asr9k-px-5.3.3.CSCux24553"],

"status": "Posted",

"superseded_by": [],

"supersedes": ["asr9k-px-5.3.3.CSCtz68435",

"asr9k-px-5.3.3.CSCux32820",

"asr9k-px-5.3.3.CSCuv63743",

"asr9k-px-5.3.3.CSCuy75598",

"asr9k-px-5.3.3.CSCuy47708",

"asr9k-px-5.3.3.CSCuy71556",

"asr9k-px-5.3.3.CSCux20499",

"asr9k-px-5.3.3.CSCuy32183",

"asr9k-px-5.3.3.CSCux85576"],

"type": "Optional",

"uncompressed_image_size": "181961047"

}

Possible Error Codes:

HTTP Code	Possible Scenario
401	Invalid credentials or expired token.
404	No results for given input.

6.4 Get Optimized Software

Given a software package list, returns a list of software packages that should be included for a successful installation. This API requires a connection to CCO to resolve software package dependencies. If CCO is not reachable and the dependency information was not previously saved in the database, the software packages submitted may be classified as ‘Unrecognized’. Below are the possible classifications denoted by the key ‘is’ in the API response.

Classification	Description
SMU/SP	A SMU or Service Pack
Package	A software package other than a SMU/SP.
Pre-requisite	A SMU that is a pre-requisite which is missing in the API request.
Superseded	A SMU that is superseded by another SMU in the resultant list. Superseded SMUs will not be included in the API response.
Unrecognized	The software package cannot be classified. Possible reasons include wrong typo or CSM Server cannot connect to CCO to validate it.

Request Parameters:

Parameter	Required	Type	Length	Description
software_packages	Yes	string	N/A	A comma delimited list of software packages.

Sample Request:

GET:
http://localhost:5000/api/v1/cco/get_optimized_software?software_packages= ncs5500-os-support-4.0.0.6-r613.CSCve17920.x86_64.rpm,ncs5500-dpa-3.0.0.22-r613.CSCve29118.x86_64.rpm

Sample Response:

{

"api_response":

{

"software_list": [

{

"description": "LWM infra to increase LWM message connect table size from 5k to 30k",

"is": "Pre-requisite",

"software_package": "ncs5500-infra-4.0.0.3-r613.CSCvc87011.x86_64.rpm"

},

{

"description": "LWM infra to increase LWM message connect table size from 5k to 30k",

"is": "Pre-requisite",

"software_package": "ncs5500-os-5.0.0.2-r613.CSCvc87011.x86_64.rpm"

},

. . .

{

"description": "Packet drops on punt/inject path of NCS5501 base model",

"is": "SMU/SP",

"software_package": "ncs5500-dpa-3.0.0.21-r613.CSCve17920.x86_64.rpm"

},

{

"description": "default port trap not capturing packets",

"is": "SMU/SP",

"software_package": "ncs5500-dpa-3.0.0.22-r613.CSCve29118.x86_64.rpm"

}]

}

7 Schedule Installation APIs

Multiple install operations can be specified through one API request. The following pre-defined strings can be used for an install action:

Install Action Strings	Description
Pre-Upgrade	Perform pre-check procedures
Add	Add packages to a device
Activate	Activate packages on a device
Post-Upgrade	Perform post-check procedures
Commit	Commit the activated packages
Remove	Remove specific packages
Remove All Inactive	Remove all inactive packages
FPD-Upgrade	Perform FPD upgrade

Certain install actions have implicit dependency built-in. When multiple install actions are specified for the same host, CSM will enforce an implicit dependency for the following install actions in the order shown below.

Pre-Upgrade ← Add ← Activate ← Post-Upgrade ← Commit

For example, if both Add and Post-Upgrade are scheduled, Add will be a dependency for Post-Upgrade. Until Add is successfully executed, Post-Upgrade will not proceed. Only one install of each install_action can be submitted in a single request per host.

Scheduling an installation involves two phases: validation and creation. In the validation phase, user input will be analyzed, and any requests with invalid or incomplete entries will be reported back to the user for resubmission. The validation phase does not check dependencies, which are calculated in the creation phase. Once all other input in the request is valid, install jobs will be created.

Note: For an example of the format for submitting multiple install operations in a single request, refer to the Multiple Host Example in the Create Host section.

Request Parameters:

Parameter	Type	Length	Description
hostname	string	N/A	The hostname of a managed host. The host must exist in the CSM database.
install_action	string	N/A	See above table for Install Action Strings.
scheduled_time	string	N/A	The time this scheduled install should execute. The scheduled time must be in "mm-dd-yyyy hh:mm AM\|PM" format. If no scheduled time is given, it will be set to the current time. * hh:mm AM\|PM should be between 12:00 AM and 11:59 PM.
server_repository	string	N/A	The server repository where the software packages can be located. The server repository must exist in the CSM database
server_directory	string	N/A	The relative path from the home directory.
software_packages	list	N/A	Add: The software package name must be locatable in the designated server repository. Activate: The software package name must appear in the Inactive Package area on the host or an external filename as on CCO. Remove: The software package name must appear in the Inactive Package area on the host. Deactivate: The software package name must appear in the Active Package area on the host.
utc_offset**	string	N/A	The UTC offset in the form <+\|->dd:dd and be between -14:00 and +12:00, e.g. +08:00 or -10:00.
command_profile	list	N/A	The custom command profile must exist in the CSM database. This parameter is not applicable to "Commit".
dependency*	string	N/A	Either the ID of the specific install job, or the install_action on which the install should be dependent.
fpd_location	string	N/A	The line card location for the FPD upgrade.
fpd_type	string	N/A	The FPD type for the FPD upgrade.

*In the case that the dependency submitted is an install_action instead of a job ID, the install job will be dependent on the latest-scheduled job of that action type that is scheduled to run earlier than the new job. In the example below, if there are two Add jobs in the database with scheduled_time earlier than the Post-Upgrade, and one Add job scheduled later than the Post-Upgrade, the Post-Upgrade will become dependent on the second of the two earlier jobs.

Dependencies will automatically be computed for jobs that are submitted for the same host in the same request as follows: Pre-Upgrade ← Add ← Activate ← Post-Upgrade ← Commit

**If scheduled_time is submitted, utc_offset is also required.

Possible Error Codes:

HTTP Code	Possible Scenario
400	Bad Request; check that POST or GET is correct.
	Input format is incorrect; should be a list of JSON objects.
	One or more input parameters is invalid, check the returned status messages.
	One or more submitted jobs was a duplicate.
401	Invalid credentials or expired token.
401	User does not have required permissions.
207	Some operations in the request failed.

7.1 Install Action: Pre-Upgrade, Post-Upgrade, Commit

Request Parameters:

Parameter	Required
hostname	Yes
install_action	Yes
scheduled_time	No
utc_offset	No
command_profile	No
dependency	No

Sample Request:

POST:
http://localhost:5000/api/v1/install

BODY:

[{
"hostname": "R2",
"install_action": "Pre-Upgrade",
"scheduled_time": "06-15-2016 03:15 PM",

  "utc_offset": "-07:00",
  "command_profile": ["Test Commands"],
  "dependency": "118"
}]

Sample Response:

The id can be used for querying the installation status and session logs.

{

"api_response": {

"install_job_list": [

{

"status": "SUCCESS",

"id": 134,

"hostname": "R2"

"install_action": "Pre-Upgrade"

}

]

}

OR

{

"api_response": {

"install_job_list": [

{

"status": "FAILED",

"scheduled_time": "06-15-2016 03:15 PM",

"hostname": "R2",

"install_action": "Pre-Upgrade",

"command_profile": ["Test Commands"],

"status_message": "Missing utc_offset."

"dependency": "118"

}

]

}

7.2 Install Action: Add

Request Parameters:

Parameter	Required
hostname	Yes
install_action	Yes
server_repository	Yes
server_directory	No
software_packages	Yes
scheduled_time	No
utc_offset	No
dependency	No

Sample Request:

POST:
http://localhost:5000/api/v1/install

BODY:

[{
"hostname": "R2",
"install_action": "Add",
"scheduled_time": "06-21-2016 07:05 AM",
"utc_offset": "-07:00",
"server_repository": "My_Repository",
"software_packages": ["asr9k-px-5.3.3.CSCuz05961.pie","asr9k-px-5.3.3.CSCux89921.pie","asr9k-px-5.3.3.CSCuy03335.pie"],

"dependency": "2"
}]

7.3 Install Action: Activate, Remove, Deactivate

Request Parameters:

Parameter	Required
hostname	Yes
install_action	Yes
software_packages	Yes
scheduled_time	No
utc_offset	No
dependency	No

Sample Request:

POST:
http://localhost:5000/api/v1/install

BODY:

[{
"hostname": "R1",
"install_action": "Activate",
"scheduled_time": "06-02-2016 08:00 AM",
"utc_offset": "-07:00",
"software_packages": ["asr9k-px-5.3.3.CSCuz05961.pie","asr9k-px-5.3.3.CSCux89921.pie","asr9k-px-5.3.3.CSCuy03335.pie"],
"dependency": "1"
}]

7.4 Install Action: FPD-Upgrade

Request Parameters:

Parameter	Required
hostname	Yes
install_action	Yes
scheduled_time	No
utc_offset	No
fpd_location*	No
fpd_type*	No
dependency	No

*If neither fpd_location nor fpd_type is specified, the install operation will apply to all locations and FPD types.

Sample Request:

POST:
http://localhost:5000/api/v1/install

BODY:

[{
"hostname": "R1",
"install_action": "FPD-Upgrade",
"scheduled_time": "06-02-2016 08:00 AM",
"utc_offset": "-07:00",
"fpd_location": "0/RP0",

"fpd_type": "IOFPGA"
}]

7.5 Get Install Jobs

Returns JSON data on install jobs specified by the id, host, install_action, or status; or jobs that have scheduled times later than or equal to the submitted scheduled_time. Multiple criteria can be used at the same time. If the submitted request would return more than 5000 entries, and error message will be shown asking the user to further refine the query until it results in fewer than 5000 entries.

Request Parameters:

Parameter	Required	Type	Length	Description
id	No	int		The id of the install job to query. If the id is specified, all other parameters will be ignored.
hostname	No	string	N/A	The host the install jobs belong to.
install_action	No	string	N/A	The install_action to query. Must be "Pre-Upgrade", "Add", "Activate", "Post-Upgrade", "Commit", "Remove", or "Deactivate".
status	No	string	N/A	Acceptable values are "scheduled", "in-progress", "completed", and "failed".
scheduled_time*	No	string	N/A	Return entries scheduled on or after the submitted time. The scheduled time must be in "mm-dd-yyyy hh:mm AM\|PM" format. * hh:mm AM\|PM should be between 12:00 AM and 11:59 PM.
utc_offset**	No	string	N/A	The UTC offset in the form <+\|->dd:dd, e.g. +08:00 or -10:00.

*If scheduled_time is specified, utc_offset must also be specified.

**If utc_offset is specified, even without a scheduled_time, all time values will be returned in local time rather than GMT.

Sample Request:

GET:
http://localhost:5000/api/v1/install
http://localhost:5000/api/v1/install?id=1
http://localhost:5000/api/v1/install?hostname=R1
http://localhost:5000/api/v1/install?hostname=R1&install_action=Add
http://localhost:5000/api/v1/install?hostname=R1&status=failed
http://localhost:5000/api/v1/install?scheduled_time= 08-02-2016 08:00

AM&utc_offset=+07:00

Sample Response:

{

"api_response": {

"install_job_list": [

{

"id": 20,

"install_action": "Add",

"dependency": 19,

"server": "My_Server",

    "software_packages": ["asr9k-px-5.3.3.CSCuz05961.pie",
    "asr9k-px-5.3.3.CSCux89921.pie",
    "asr9k-px-5.3.3.CSCuy03335.pie"],

"pending_downloads": "",

"scheduled_time": "Wed, 01 Jun 2016 15:15:00 GMT",

"start_time": "Wed, 01 Jun 2016 15:20:00 GMT",

"status": "scheduled",

"status_time": ""

"trace": "",

"created_by": "root",

"hostname": "R1",

"custom_command_profile": []

}

]

}

Possible Error Codes:

HTTP Code	Possible Scenario
400	Bad Request; check that POST or GET is correct.
	Unknown page number; there are fewer results than would require the number of pages input.
	Invalid input parameter, i.e. misspelled hostname, etc. Check that all input is correct.
	Missing required parameter, make sure all required parameters are submitted, including utc_offset if providing a scheduled_time.
	"Too many results; please refine your request." The submitted criteria return too many results. The user must further refine the query by changing or adding more parameters to the request.
401	Invalid credentials or expired token.
401	User does not have required permissions.

7.6 Delete Install Jobs

Deletes install jobs specified by the id, host, or status. It will also delete any install jobs dependent on the jobs specified. Only jobs that are scheduled or failed, not in-progress or completed, can be deleted.

Request Parameters:

Parameter	Required	Type	Length	Description
id	No	int	N/A	The id of the install job to delete.
hostname	No	string	N/A	The hostname for which all jobs that are not in-progress should be deleted.
status	No	string	N/A	Acceptable values are "failed" or "scheduled". Cannot delete in-progress jobs or completed jobs.

Sample Request:

DELETE:
http://localhost:5000/api/v1/install/delete?id=180

http://localhost:5000/api/v1/install/delete?hostname=R1
http://localhost:5000/api/v1/install/delete?hostname=R1&status=failed

Sample Response:

{

"api_response": {

"install_job_list": [

{

"deleted_dependencies": [

44,

45,

46,

47

],

"hostname": "R2",

"id": 43,

"install_action": "Pre-Upgrade",

"status": "SUCCESS"

}

]

}

Possible Error Codes:

HTTP Code	Possible Scenario
400	Bad Request; check that POST or GET is correct.
400	Invalid value for a parameter.
401	Invalid credentials or expired token.
401	User does not have required permissions.

7.7 Get Logs

Download the session logs for a particular install job.

Request Parameters:

Parameter	Required	Type	Length	Description
id	Yes	int	N/A	The id of the install job.

Sample Request:

GET:
http://localhost:5000/api/v1/install/logs/180

Receiving zip from response:

The http response will include a zip file containing all of the log files. An example in python for retrieving and extracting that zip file is as follows:

import requests

import zipfile

import io

resp = requests.get("http://localhost:5000/api/v1/install/logs/13",auth=(token, "unused"))

try:

zip = zipfile.ZipFile(io.BytesIO(resp.content))

zip.extractall(directory_path)

except zipfile.BadZipfile:

print "No session logs."

"directory_path" is a string containing the exact path to an existing directory.

Possible Error Codes:

HTTP Code	Possible Scenario
400	Bad Request; check that POST or GET is correct.
400	ID invalid or not specified.
401	Invalid credentials or expired token.
401	User does not have required permissions.

End of Document

Cisco Software Manager API Guide

1 Host APIs

1.1 Create Hosts

1.2 Get Hosts

1.3 Delete Host

2 Jump Host APIs

2.1 Create Jump Host

2.2 Get Jump Hosts

2.3 Delete Jump Hosts

3 Region APIs

3.1 Create Region

3.2 Get Regions

3.3 Delete Region

4 Server Repository APIs

4.1 Create Server Repositories

4.2 Get Server Repositories

4.3 Delete Server Repositories

5 Custom Command Profile APIs

5.1 Create Custom Command Profiles

5.2 Get Custom Command Profiles

5.3 Delete Custom Command Profiles

6 CCO APIs

6.1 Get CCO Catalog

6.2 Get CCO Software

6.3 Get CCO Software Entry

6.4 Get Optimized Software

7 Schedule Installation APIs

7.1 Install Action: Pre-Upgrade, Post-Upgrade, Commit

7.2 Install Action: Add

7.3 Install Action: Activate, Remove, Deactivate

7.4 Install Action: FPD-Upgrade

7.5 Get Install Jobs

7.6 Delete Install Jobs

7.7 Get Logs