cancel
Showing results for 
Search instead for 
Did you mean: 
cancel

Cisco Software Manager API Guide

1777
Views
0
Helpful
0
Comments

 

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

1     Host APIs. 3

1.1       Create Hosts. 3

1.2       Get Hosts. 5

1.3       Delete Host 6

2     Jump Host APIs. 7

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.

Bad input parameters—check that valid input was given.

401

Invalid credentials or expired token.

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.

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.

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.

Bad input parameters—check that valid input was given.

401

Invalid credentials or expired token.

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.

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.

Bad input parameters—check that valid input was given.

401

Invalid credentials or expired token.

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.

Bad input parameters—check that valid input was given.

401

Invalid credentials or expired token.

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.

Unknown region; the region provided does not exist in the database. Check that the name was input correctly.

401

Invalid credentials or expired token.

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.

Bad input parameters—check that valid input was given.

401

Invalid credentials or expired token.

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.

Bad input parameters—check that valid input was given.

401

Invalid credentials or expired token.

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.

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.

Bad input parameters—check that valid input was given.

401

Invalid credentials or expired token.

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.

Bad input parameters—check that valid input was given.

401

Invalid credentials or expired token.

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.

Unknown region; the region provided does not exist in the database. Check that the name was input correctly.

401

Invalid credentials or expired token.

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.

Bad input parameters—check that valid input was given.

401

Invalid credentials or expired token.

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.

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.

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.

Invalid value for a parameter.

401

Invalid credentials or expired token.

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.

ID invalid or not specified.

401

Invalid credentials or expired token.

User does not have required permissions.

 

 

 

End of Document

CreatePlease to create content
Content for Community-Ad

Cisco COVID-19 Survey

This widget could not be displayed.