cisco prime performance manager rest api guide, 1...prime performance manager 1.2 user guide and...

Cisco Prime Performance Manager REST API Guide

Copyright 2012 Cisco Systems - 1 -

Cisco Prime Performance Manager 1.2

REST API Guide June 15, 2012



Table of Contents

1 Purpose ........................................................................................................................................... 3

2 Assumptions ................................................................................................................................... 4

2.1 Audience.................................................................................................................................. 4

2.2 HTTP Version ......................................................................................................................... 4

2.3 SSL and HTTP ........................................................................................................................ 4

2.4 Read Only API ........................................................................................................................ 4

2.5 Versioning ............................................................................................................................... 4

3 Prime Performance Manager REST API Installation.................................................................. 4

4 Reports Default Time Durations ................................................................................................... 4

5 REST API Components................................................................................................................. 5

5.1 Content-Type........................................................................................................................... 5

5.1.1 Accept Header Preference ............................................................................................... 6

5.2 Character Set Encoding .......................................................................................................... 6

5.3 URI Syntax .............................................................................................................................. 6

5.4 HTTP Verb .............................................................................................................................. 7

5.5 Resources................................................................................................................................. 7

5.5.1 List of Reports – Collection Resource............................................................................ 7

5.5.2 Report – Document Resource ......................................................................................... 8

5.6 URL Encoding ........................................................................................................................ 8

5.7 Query String Parameters ........................................................................................................ 8

5.7.1 FQDN ............................................................................................................................... 9

5.7.2 sgmid ................................................................................................................................ 9

5.7.3 startDate.......................................................................................................................... 10

5.7.4 endDate........................................................................................................................... 10

5.7.5 durationSelect................................................................................................................. 11

5.7.6 intervalTypeKey ............................................................................................................ 12

5.7.7 pageIndex ....................................................................................................................... 12

5.7.8 maxPageSize .................................................................................................................. 12

5.7.9 outputType ..................................................................................................................... 13

5.7.10 csvHeader.................................................................................................................... 13



5.7.11 showAllReports .......................................................................................................... 13

5.8 REST Parameter Rules ......................................................................................................... 14

5.9 HTTP Request Headers ........................................................................................................ 14

5.9.1 Accept ............................................................................................................................. 14

5.9.2 Authorization.................................................................................................................. 15

5.10 HTTP Response Headers .................................................................................................. 15

5.11 HTTP Status Code ............................................................................................................. 16

5.12 Error Responses ................................................................................................................. 17

6 REST APIs ................................................................................................................................... 18

6.1 GET /reports/{category}.. .................................................................................................... 18

6.1.1 Description ..................................................................................................................... 18

6.2 Reports Listing Samples....................................................................................................... 18

6.2.1 CSV................................................................................................................................. 19

6.2.2 JSON............................................................................................................................... 19

6.2.3 XML ............................................................................................................................... 20

6.3 GET /reports/{category}../{reportName} ........................................................................... 21

6.3.1 Description ..................................................................................................................... 21

6.4 Report Samples ..................................................................................................................... 21

6.4.1 CSV................................................................................................................................. 22

6.4.2 JSON............................................................................................................................... 22

6.4.3 XML ............................................................................................................................... 23

7 Pagination ..................................................................................................................................... 25

8 References .................................................................................................................................... 25

9 Glossary ........................................................................................................................................ 26

1 Purpose This document describes the Cisco Prime Performance Manager Representational State Transfer (REST) API used to retrieve reports data from Prime Performance Manager. The REST API is implemented as a web service front-end component on the Prime Performance Manager gateway. The API allows applications to retrieve performance data from the gateway using HTTP(s) GET requests with the URLs specified in this document.

The data provided by the REST API can be formatted as XML (eXtensible Markup Language), JSON (JavaScript Object Notation), or CSV (comma separated value). The report data format is based on the request HTTP Accept Header or the value of the “outputType” query string parameter. If no specific data type is requested, the report data defaults to CSV.



2 Assumptions 2.1 Audience This document is intended for developers who wish to implement the network management RESTFul client to consume performance reporting data from the Prime Performance Manager application. The audience is assumed to be familiar with RESTful web services and the HTTP protocol.

2.2 HTTP Version The Reports REST API embraces several aspects of the HTTP standards, includin g some headers, HTTP verbs, and status codes. The REST API uses status codes that are only supported in the HTTP/1.1 version. Therefore, it is expected that the client consuming this API complies with these HTTP/1.1 features.

2.3 SSL and HTTP This API is served over an HTTPs secure connection when the Prime Performance Manager server has SSL installed an d enabled. In this case the client side must support the HTTP/SSL protocol and have the Prime Performance Manager SSL public certificate installed on the client’s thrust store file.

2.4 Read Only API This REST API is used for reading network performance reporting data. It supports the HTTP GET method which does not affect the state of the resource being queried in the server.

2.5 Versioning The Prime Performance Manager Reports REST API complies with the following versioning rule: elements may be added when releasing a new version, but they may never be removed. A new release of this API is expected to be down ward compatible with a previous version. An older version of this Reports REST API might appear to the client as if some elements were removed.

3 Prime Performance Manager REST API Installation

This document does not tell you how to install or configure Prime Performance Manager. See the Cisco Prime Performance Manager 1.2 User Guide and Cisco Prime Perfo rmance Manager 1.2 Quick Start Guide for installation and configuration procedures. Also, the steps to configure SSL and authentication are not provided, as that pertains to the Prime Performance Manager server.

The Reports REST API is a Prime Performance Manager gateway component. All code needed to run and test the Reports REST API is included in the Prime Performance Manager installation. After you install Prime Performance Manager, no additional Prime Performance Manager Reports REST API configuration is needed.

4 Reports Default Time Durations The reporting data returned from the PPM REST API has the durations shown in the following table, based off the interval (intervalTypeKey parameter). If the startDate and endDate parameters are provided



in the URL (refer to Query String Parameters), the duration is constrained by the time difference between the endDate and startDate.

Table 1 - Report Default Durations

Interval intervalTypeKey (parameter) Duration

5 min FIVE_MINUTE Last 6 hours

15 min1 QUARTER_HOUR Last 12 hours

Hourly 2 HOUR Last 24 hours

Daily DAY Last 30 days

Weekly WEEK Last 6 months

Monthly MONTH Last 1 year

5 REST API Components

5.1 Content-Type The report data provided by the REST API can be formatted as XML, JSON, or CSV. The data format is based on the values of the incoming HTTP Accept header or the “outputType” query string parameter. If no specific data format type is found in the incoming request, the REST API defaults the response data format and content-type to “text/csv”.

The response content-type may be specified usin g either the HTTP request “Accept” header or the “outputType” parameter. The “outputType” parameter has precedence over the “Accept” header. If neither the “outputType” parameter nor the “Accept” header (or if the Accept header found matches */*), the content-type defaults to “text/csv”.

The following “outputType” parameter values can be used:

For CSV: “csv”

For JSON: “ json”

For XML: “xml”

When using the HTTP “Accept” header, the following can be used:

For CSV: text/csv; charset="utf-8" (RFC 4180)

For JSON: application/json (RFC 4627)

For XML: text/xml OR application/xml (RFC 3023)

1 Node speci fic reports are by default rendered as 15 min interval reports. A node report requires either an FQDN node or sgmid value to be provided as a query string parameter in the REST API URL. 2 Network level reports are by default rendered as hourly reports. Network l evel reports consist of data for the top node el ements. It is the default report when no FQDN or sgmid query string parameter is provided in the REST API URL.



Defaults to CSV: * or */*

Notice that a 406 status is returned for an Accept header that is not supported by the REST API.

5.1.1 Accept Header Preference When the “Accept” header contains more than one accept type supported by the REST API, the following order of preference is followed:

CSV - > JSON - > XML

For example,

Accept: text/xml, text/csv, application/json -- CSV is selected

Accept: application/json, text/csv -- CSV is selected

Accept: text/xml, application/json – JSON is selected

Accept: application/xml, text/csv, application/json – CSV is selected

Accept: text/html, */*, text/xml – XML is selected

Accept: text/html, */* – default to CSV due to the */*

Accept: text/html, image/jpeg, * -- default to CSV due to *

Accept: text/html, image/jpeg, text/plain -- 406 error is returned.

5.2 Character Set Encoding This Reports REST API defaults all the responses to the “UTF-8” charset encoding, irrespective of the requested charset sent.

5.3 URI Syntax The REST API calling URI syntax is defined as follo ws:

Table 2 – URL Syntax

URL Syntax {scheme}://{host}:{port}/ppm/rest/reports/{resource}?{parameters=…}..

Table 3 – URL Parts

URL Parts Sample Value Description

scheme http or https Use https when Prime Performance Manager SSL is enabled; otherwise, it should be http.

Host For example: “ppm-clean.cisco.com”

Note: use your own domain name above.

The host name assigned to the Prime Performance Manager gateway server



Port For example: 4440 HTTP port number assigned to the Prime Performance Manager gateway server. Note that the same port number may be used when Prime Performance Manager is running in SSL enabled mo de.

Path prefix /ppm/rest/ All the REST API paths must be prefixed with this value. This is the entry point to the REST API.

Store /reports Both collection resources (listing of reports) and document resource (report data itself) are specified from this parent URI.

Resources /{category}..

/{category}../{reportName}

A collection resource containing listing of all report category, sub-categories an d corresponding report names URIs in the system.

A document resource containing the report information (data) itself which can be filtered using query string parameters.

Parameters outputType, FQDN,sgmid, startDate, endDate, durationSelect, …

Refer to Query String Parameters

5.4 HTTP Verb The Reports REST API is read-only. It only supports the HTTP GET verb. The following table sho ws an example of a URL and corresponding GET request to retrieve a list of reports elements in JSON format:

Ta ble 4 – HTTP URL Report List Sample

http://ppm-clean.cisco.com:4440/ppm/rest/reports?outputType=json

GET /ppm/rest/reports?outputType=json

5.5 Resources

5.5.1 List of Reports – Collection Resource Example: GET /ppm/rest/reports/{category}..

The REST API provides a directory listing of all the report categories, subcategories and report names. This type of resource is generally known as a collection resource. It allows you to gather a list of all resources (documents) in the system.

Prime Performance Manager reports are grouped by a specific {category}. A category is a unique name in the Prime Performance Manager system used to identify a group of reports. Categories consist of



subcategories that form a hierarchical path to various reports in the system. Therefore, you can have several categories within a single path that combined together gives the full path to a specific report.

Table 5 – List of Report Examples

Resource Name Description /reports/{category}.. The list of reports for that category. An empty {category}

implies the root category that shows all the top report categories.

/reports /Availability

List all reports subcategories and reports (if any) under the “Availability” category.

/reports/Availability/ICMP+Ping List all reports subcategories and reports (if any) under the “ICMP Ping” category. Note: “+” (plus-sign) represents a space in the URL.

5.5.2 Report – Document Resource Example: GET /ppm/rest/reports/{category}../{reportName}?{query String}

The REST API provides data about various sy stem reports. This resource type is generally known as a document. A report document contains the data associated with a given report filtered by any query parameters passed in (FQDN, sgmid, start/end date). Prime Performance Manager reports are uniquely identified by a {reportName} and a specific {category}.

Notice that {query String} parameters (FQDN, sgmid, startDate, endDate, …) are used to filter out the reporting data for a given the report document resource.

Table 6 – Report Example

Resource Name Description /reports/Availability/ICMP+Ping/ICMP+Ping+Availability A report identified by the

{reportName} “ICMP Ping Availability” which is part of the “ICMP Ping” {category}.

5.6 URL Encoding The URL must be encoded according to the Internet URL standards (RFC 3986). Some characters are not considered safe for URL use. These must be properly converted to their encoded counterpart prior to URL request submission. For safety, always encode the parameter values before you submit the request. For further information, see to the Internet standards (RFC 3986).

The server side of the REST API always decodes the passed in parameter values accordin g to RFC 3986 standards. Therefore, the client side must always encode the parameter values usin g the same standards.

Note: The “+” (plus-sign) represents a space in the URL. If you want to pass a plus (+) character as part of a parameter value (for example, 2006-08-25T15:30+0800), you must encode the “+” to its respective URL encoded form “%2B”.

5.7 Query String Parameters The following tables sho w the REST API request parameters. The REST API is usin g a subset of the HTTP request parameters found in the Prime Performance Manager web based application. This allows



the REST API and Prime Performance Manager web based application to have consistent names. This also allo ws the same values used in the web based GUI to be passed to the REST API.

Note:

- Parameter names/values are case-sensitive- Parameter values should be encoded to escape non-safe HTTP characters.

.

- Some parameters are mutually exclusive.

5.7.1 FQDN Table 7 – FQDN Parameter

Parameter Notes FQDN The FQDN (Fully Quali fi ed Domain Name) value as defined in the Prime Performance

Manager Server Format: Node=<host or IP>,<other keys as defined in the corresponding report XML file> Following are examples of valid formatt ed FQDN values. Node=em1941kbf. cisco.com Node=10.74.125.210 Node=em1941kbf. cisco.com,i fDescr=FastEthernet0/0 Node=10.74.125.210,CPUSlot=0,CPUNum=0,processorIndex=1 Refer to your Prime Performance Manager server or network to det ermine your own FQDN values.

Additional Notes 1) Only supported in the “ GET /reports/{cat egory}../{reportName}” requests. 2) If an FQDN or sgmid is not provided, the REST API defaults to a top network level report. A network level

report consists of information for the top samples in that report met ric. 3) Refer to the Prime Performance Manager documentation for more information about network level reports.

5.7.2 sgmid Table 8 – sgmid Parameter

Parameter Notes sgmid A positive integer number that uniquely identi fi es a node in the Prime Performance

Manager server Format: Positive integer number greater than 0 (eg. 1002, 13001, ..). -1 is also accepted, and it is optional. See note (3) below. Refer to your Prime Performance Manager server or network to det ermine your own FQDN values

Additional Notes • Only supported in the “ GET /reports/{cat egory}../{reportName}” requests. • If an FQDN or sgmid is not provided, the REST API defaults to a top network level report. A network level

report consists of information for the top samples in that report met ric. Refer to the Prime Performance Manager documentation for more information about network-level reports.

• For consist ency with the Prime Performance Manager web based application an “ sgmid” equal to -1means a network level report. However, this “ sgmid” parameter value is not requi red as a network level report is already assumed when “ FQDN” and “ sgmid” are not given.



5.7.3 startDate Table 9 – startDate Parameter

Parameter Notes startDate The start dat e for the reporting data.

Format: yyyy-MM-ddTHH:mmZ where, yyyy: year (eg. 2010, 2011, 2012…) MM: month in year (eg, 1-12) dd: day in month (eg. 1, 2,…,31) T: charat er to separat e dat e from time. HH: hour in day (0-23) mm: minute in hour (0-59) Z: time zone represented as follows (+/ -)HHmm “+” to add or “ -“ to subtract the “ HHmm” from the GMT time. Examples: 2012-3-23T12:30+ 0800 2012-12-23T2:05+0800 Note: “+” needs to be encoded to “% 2B” prior to being sent on the HTTP request.

Additional Notes • Only supported in the “ GET /reports/{cat egory}../{reportName}” requests. • The “ startDate”/“ endDate” and “ durationSelect” parameters are mutually exclusive. • If the “ startDate” is not given, it will default to the cal culat ed value based on “ durationS elect” and

“ endDate” (or system time i f “ endDate” is not given). • If both startDate and endDate are given, their timezone must match. For example:

startDate is not given. endDate=”2012-03-23T12:30+0800” duration=”last24Hours” intervalTypeKey=”HOUR” The startDate is 24 hours less than the “ endDate”; that is “ 2012-03-22T12:30+0800”

• The “ startDate” may be cal cul ated to be a dat e in the future. In that case, keep in mind that no reporting information is availabl e in the system for a future dat e.

• If “ startDate” and “ endDate” are not given, the current server time is used for the “ endDate”. The “ startDate” is cal culat ed by subt racting the “ durationSelect ” from the current time. In this case, the date/times will all be set according to the server timezone settings.

• Provide either the start or end date with proper GMT offset to ensure the reporting dat a received are in the expect ed timezone.

5.7.4 endDate Table 10 – endDate Parameter

Parameter Notes endDate The end dat e for the reporting dat a.

Format: yyyy-MM-ddTHH:mmZ where,



yyyy: year (eg. 2010, 2011, 2012…) MM: month in year (eg, 1-12) dd: day in month (eg. 1, 2,…,31) T: charat er to separat e dat e from time. HH: hour in day (0-23) mm: minute in hour (0-59) Z: time zone represented as follows (+/ -)HHmm “+” to add or “ -“ to subtract the “ HHmm” from the GMT time. Example: 2012-04-23T02:30+0800 Note: “+” needs to be encoded to “% 2B” prior to being sent on the HTTP request.

Additional Notes • Only supported in the “ GET /reports/{cat egory}../{reportName}” requests. • The “ startDate”/“ endDate” and “ durationSelect” parameters are mutually exclusive. • If the “ endDate” is not given, it will default to the cal culat ed value based on “ durationSelect ” and

“ startDate” (or system time i f “ startDate” is not given). • If both startDate and endDate are given, their timezone must match. For example,

endDate is not given. startDate=”2012-03-22T12:30+0800” duration=”last24Hours” intervalTypeKey=”HOUR” The endDate is 24 hours plus the “ startDate”; that is “ 2012-03-23T12:30+0800”

• The “ endDate” may be calcul ated to be a dat e in the future. In that case, the user should keep in mind that no reporting information is availabl e in the system for a future dat e.

• If “ startDate” and “ endDate” are not given, the REST API will det ermine the “ startDate” and “ endDate” using the timezone set in the Prime Performance Manager server. In this case, the dat es/times where REST client application is running and the dates/times set in the server may be di fferent.

• The user should provide either the start or end dat e with proper GMT offset to ensure the reporting data received are in the expect ed timezone.

5.7.5 durationSelect Table 11 – durationSelect Parameter

Parameter Notes durationSelect The duration int erval used for the reporting data. Possible values:

last5Years last1Year last6Months last90Days last60Days last30Days last21Days last7Days last3Days lastDay or last24Hours last12Hours last6Hours lastHour

Additional Notes • Only supported in the “ GET /reports/{cat egory}../{reportName}” requests. • The “ startDate”/“ endDate” and “ durationSelect” parameters are mutually exclusive.



• The default value is last24Hours4

for network level report, unless the “ intervalTypeKey” parameter is provided (refer to document section Reports Default Time Durations).

• The default value is last12Hours4

for a speci fi c node report, unless the “ intervalTypeKey” parameter is provided (refer to document section Reports Default Time Durations).

• The durationS elect must be greater than intervalTypeKey. Default values for “ durationSelect” are based on “ intervalTypeKey” -- refer to document section 4 Reports Default Time Durations.

5.7.6 intervalTypeKey Table 12 – intervalTypeKey Parameter

Parameter Notes intervalTypeKey The average interval type for the measurements in the reporting dat a.

Possible values: FIVE_MINUTE QUARTER_HOUR HOUR DAY WEEK MONTH

Additional Notes • Only supported in the “ GET /reports/{cat egory}../{reportName}” requests. • The default is HOUR

The default is for network level reports; that is, when “ FQDN” or “ sgmid” are not given.

QUARTER_HOUR

5.7.7 pageIndex

for a node level report; that is, either “ FQDN” or “ sgmid” is given.

Table 13 – pageIndex Parameter

Parameter Notes pageIndex The report page number being requested for multi-page reports.

Format: a positive int eger number greater than 0.

Additional Notes • Only supported in the “ GET /reports/{cat egory}../{reportName}” requests.

5.7.8 maxPageSize Table 14 – maxPageSize Parameter

Parameter Notes maxPageSize The total number of records in the response.

Format: a positive integer number great er than 0.

Additional Notes • Only supported in the “ GET /reports/{cat egory}../{reportName}” requests. • The default is 1000• This parameter represents the maximum number of records found in the report, and not on the page.

.

• The parameter name was maitained to be consistent with the same parameter name used in the Prime Performance Manager web based application.



5.7.9 outputType Table 15 – outputType Parameter

Parameter Notes outputType The content-type det ermines the expect ed format of the dat a in the

response. This parameter, when provided, overrides the value defined in the HTTP “ Accept” header. Possible values: csv xml json

Additional Notes • This parameter is support ed in all requests. • The default value is csv

5.7.10 csvHeader

.

Table 16 – csvHeader Parameter

Parameter Notes csvHeader The csvHeader may be used to disable headers in CSV responses. By

default CSV content contains headers in the first line. If the user does not want to see headers in the fi rst line, this parameter should be set to “ false”. Possible values: true (default) false

Additional Notes • This parameter is support ed in all requests. • The default value is true

5.7.11 showAllReports

.

Table 17 – showAllReports Parameter

Parameter Notes showAllReports The showAllR eports may be used to list all reports within a given

cat egory or sub-category. This parameter only applies when listing the reports in the Prime Performance Manager system. Possible values: This parameter is an empty parameter. It does not accept a value.

Additional Notes • This parameter is only applicabl e to generate a listing of reports. • There is no default value, as this parameter stands on its own



5.8 REST Parameter Rules The following request parameters rules are enforced by the REST API.

• Only parameters identified in the Request Parameters are accepted.

• Parameter names and values are case sensitive.

• Parameter values must be properly formatted according to their fomat specificifications.

• FQ DN and sgmid are mutually exclusive.

• FQ DN or sgmid must correspond to a valid node found in the Prime Performance Manager system.

• startDate , endDate and durationSelect are mutually exclusive.

• endDate must be greater than startDate .

• durationSelect must be greater than intervalTypeKey.

• showAllReports must not contain a value.

5.9 HTTP Request Headers The following table has the HTTP Request headers supported.

5.9.1 Accept Table 18 – Accep t HTTP Header

Header Name Notes Accep t The requested content-type for the response. This header indicat es to the REST API

server the media type of the response expected by the client. When this header is present the REST API will attempt to respond to the client using that media type; unless, that content -type is not supported by the REST API for the request ed resource. Note that the media type can be overriden by the outputType parameter. Also, note that the REST API currently does not parse/process quality factor “ qvalues” scal e (0 to 1) parameters that may be found on the accept header. As per RFC 2616 (14.1 Accept), the “ qvalue” is a parameter beginning with the l etter “ q” that may be present on the accept header to indicate the rel ative preference for a speci fi c media type. When multiple media types are provided, the REST API will select one of them in this order: text/csv - > appli cation/json - > application/xml Possible supported values are: text/csv application/xml application/json Note: If no Accept header is found, or if “*/*”, the response will default to the text/ csv media t ype.

Additional Notes:



• The outputType parameter overrides this header. • Refer to Content -Type for more information. • The default content-type is text/ csv

5.9.2 Authorization

.

Table 19 – Authorization HTTP header

Header Name Notes Authorization This is a request header that should be sent to the REST API when the underlying

Prime Performance Manager server has user access enabled. The speci fics of how this header should be formatted is defined in the RFC 2616 HTTP 1.0 standards – section 14.8 Authori zation of RFC 2616. Format: Refer to section 14.8 RFC 2616 Authorization header.

Additional Notes: • Veri fy that this header is sent with the request i f Prime Performance Manager has user access enabled • The userId and password defined in the Prime Performance Manager server must be base64 encoded and

added to the header as defined in the HTTP standards.

5.10 HTTP Response Headers The following table shows the HTTP Response headers supported.

Table 20 – HTTP Response Headers

Header Name Sample Value Description

Allow

(HTTP/1.1)

For example, “GET” This header is generated along with status code “405” in response to request with a method (HEAD, POST, PUT, DELETE) that is not supported for that resource.

Cache-Control

(HTTP/1.1)

For example, “no-cache” OR “max-age=3600” When “no-cache” is found the client should not cache the response. Otherwise if max-age is found, response may be cached by the client. And the max-age value tells the client how long in seconds the response should be cached.

Content-Type For example. “application/xml;charset=UTF-8”

The content-type of the response followed by the charset encoding.

Date For example. “Date Fri, 27 Jan 2012 20:29:02 GMT”

The date the response was created.

WWW-Authenticate

“Basic realm=RESTSecureArea” This header is sent back to the client when Prime Performance



Manager has user access (authentication) enabled, and the system failed to authenticate the user’s request (see the Authorization Request header above). This response header conforms to the HTTP Basic WWW-Authenticate header defined in HTTP 1.0 standards.

Content-Range pages <page num ber>/<total pages

For example. “pages 2/10”

In the example the current response contains page 2 of a report that has 10 pages total.

This response header is sent back when there is more than one page available for the requested report.

5.11 HTTP Status Code The following table shows the HTTP Status codes supported.

Table 21 – HTTP Status Codes

Status Code Description

200 OK response. The request was correctly processed, and a response with a content body was produced.

204 No content found. That is, the request was a valid request; however, the system did not have any content available for the resource requested. For example, this wo uld be the case for a valid report that has no data in it .

Notice that no message-body (no content) is found in an HTTP response that has 204 as the status code.

206 Partial content. This status code is returned when a partial set of the report data has been returned. It is sent along with a “Content-Range” header.

400 Bad Request. This happens when the request has an invalid parameter, or it is missin g a required parameter. Or it could also be the case when the requested resource path is not in the expected syntax.

401 Authentication Failed. This status code is generated when the Prime Performance Manager server is running with user access (authentication) enabled, and the REST API server was unable to authenticate the user.

404 Reso urce Not Found. This status code is generated when the requested reso urce does not exist in the Prime Performance Manager REST API server. For example, if the request is for a reportId that is not found on the Prime Performance Manager server.

405 Method Not Allowed. This status code is generated when the requested method (HEAD, POST, PUT or DELETE) is not supported for that resource.



406 Not Acceptable. This status code is generated when the “Accept” header sent in the request is not supported by the REST API.

415 Unsupported Media Type. This status code is generated when the requested content-type is not supported for that resource. For example, let’s say a given report is only be available in CSV, and the client request that report using XML in the content-type. In this case, the 415 error is generated.

500 Internal Error. This error code is sent back for unexpected error on the server. If this error occurs, the user should retry the same request. If the error continues the user should verify the server logs.

5.12 Error Responses In addition to HTTP header status code, the error response contains a content component. The following table shows error response samples. All the other error responses follow a similar format.

Table 22 - CSV Request / Error Response Sample – Invalid HTTP Verb

Request / Error Response (CSV) - Invalid HTTP Verb: POST Request POST /ppm/rest/reports/ HTTP/1.1 Content-Length: 0 Content-Type: text/plain; charset=UTF-8 Host: ppm-cls-vm05.cisco.com:4440 Connection: Keep-Alive User-Agent: RestClient-Tool Response HTTP/1.1 405 Method Not Allowed Transfer-Encoding: chunked Date: Wed, 28 Mar 2012 16:12:11 GMT Allow: GET Content-Type: text/csv;charset=UTF-8 Server: Apache-Coyote/1.1 Cache-Control: no-cache error_code,error_message UnsupportedHttpVerb,HTTP method [POST] is not supported.

Table 23 - JSON Requ est / Error Response Sample - Invalid HTTP Verb

Request / Error Response (Json) – Invalid HTTP Verb: POST Request – Notice, the Accept header is set for “application/json”. POST /ppm/rest/reports/ HTTP/1.1 Accept: application/json Content-Length: 0 Content-Type: text/plain; charset=UTF-8 Host: ppm-cls-vm05.cisco.com:4440 Connection: Keep-Alive User-Agent: RestClient-Tool Response HTTP/1.1 405 Method Not Allowed Transfer-Encoding: chunked Date: Sun, 01 Apr 2012 07:50:28 GMT Allow: GET Content-Type: application/json;charset=UTF-8 Server: Apache-Coyote/1.1 Cache-Control: no-cache { "error": { "code": "UnsupportedHttpVerb",



"message": "HTTP method [POST] is not supported." } }

Table 24 - XML Request / Error Response Sample - Invalid HTTP Verb

Request / Error Response (XML) – Invalid HTTP Verb: POST Request – Notice, the Accept header is set for “application/xml”. POST /ppm/rest/reports/ HTTP/1.1 Accept: application/xml Content-Length: 0 Content-Type: text/plain; charset=UTF-8 Host: ppm-cls-vm05.cisco.com:4440 Connection: Keep-Alive User-Agent: RestClient-Tool Response HTTP/1.1 405 Method Not Allowed Transfer-Encoding: chunked Date: Wed, 28 Mar 2012 18:47:05 GMT Allow: GET Content-Type: application/xml;charset=UTF-8 Server: Apache-Coyote/1.1 Cache-Control: no-cache <?xml version="1.0" encoding="UTF-8" standalone="yes" ?> <error xmlns:ppm="http://www.cisco.com/ppm/rest/reports"> <code>UnsupportedHttpVerb</code> <message>HTTP method [POST] is not supported.</message> </error>

6 REST APIs The APIs are composed of a GET URI + reso urce + parameters (or parameters) combination.

6.1 GET /reports/{category}..

6.1.1 Description This API is used to retrieve a list of subcategories and reports for the given category. An empty {category} implies a list of top level categories. Reports are defined in a hierarchical grouping of categories and subcategories.

The following table shows a sample request for the top level report categories. Notice that if the Prime Performance Manager server has SSL enabled, you should a lso include the Authorization header.

Table 25 - – HTTP List of Reports Request Sample – Top Level Category

HTTP Request Sample – List of Reports GET /ppm/rest/reports/ HTTP/1.1 Host: ppm-cls-vm05.cisco.com:4440 Connection: Keep-Alive User-Agent: RestClient-Tool

6.2 Reports Listing Samples Note: The following samples were collected from a development server. These samples are provided to illustrate the data structure of the different data format types: XML, JSON, CSV. The data provided by your server will likely be different.



6.2.1 CSV Table 22 - CSV Request / Response Sample – List of Reports

Request / Response (CSV) – List of Reports Request GET /ppm/rest/reports/ HTTP/1.1 Host: ppm-cls-vm05.cisco.com:4440 Connection: Keep-Alive User-Agent: RestClient-Tool Response HTTP/1.1 200 OK Transfer-Encoding: chunked Date: Wed, 09 May 2012 15:34:16 GMT Content-Type: text/csv;charset=UTF-8 Server: Apache-Coyote/1.1 Cache-Control: 3600 name,uri Application Traffic,http://ppm-cls-vm05.cisco.com:4440/ppm/rest/reports/Application+Traffic/ Availability,http://ppm-cls-vm05.cisco.com:4440/ppm/rest/reports/Availability/ IP Protocols,http://ppm-cls-vm05.cisco.com:4440/ppm/rest/reports/IP+Protocols/ IP QoS,http://ppm-cls-vm05.cisco.com:4440/ppm/rest/reports/IP+QoS/ IP SLA,http://ppm-cls-vm05.cisco.com:4440/ppm/rest/reports/IP+SLA/ Mobile IOS Statistics,http://ppm-cls-vm05.cisco.com:4440/ppm/rest/reports/Mobile+IOS+Statistics/ Mobile StarOS Statistics,http://ppm-cls-vm05.cisco.com:4440/ppm/rest/reports/Mobile+StarOS+Statistics/ Resources,http://ppm-cls-vm05.cisco.com:4440/ppm/rest/reports/Resources/ Security,http://ppm-cls-vm05.cisco.com:4440/ppm/rest/reports/Security/ Transport Statistics,http://ppm-cls-vm05.cisco.com:4440/ppm/rest/reports/Transport+Statistics/ Video Broadcast,http://ppm-cls-vm05.cisco.com:4440/ppm/rest/reports/Video+Broadcast/

6.2.2 JSON Table 26 - JSON Requ est / Response Sample – List of Reports

Request / Response (JSON) – List of Reports Request – Notice, the Accept header is set for “application/json”. GET /ppm/rest/reports/ HTTP/1.1 Accept: application/json Host: ppm-cls-vm05.cisco.com:4440 Connection: Keep-Alive User-Agent: RestClient-Tool Response HTTP/1.1 200 OK Transfer-Encoding: chunked Date: Wed, 09 May 2012 15:31:05 GMT Content-Type: application/json;charset=UTF-8 Server: Apache-Coyote/1.1 Cache-Control: 3600 { "reports": { "reportInfo": [ { "name": "Application Traffic", "uri": "http://ppm-cls-vm05.cisco.com:4440/ppm/rest/reports/Application+Traffic/" }, { "name": "Availability", "uri": "http://ppm-cls-vm05.cisco.com:4440/ppm/rest/reports/Availability/" }, { "name": "IP Protocols", "uri": "http://ppm-cls-vm05.cisco.com:4440/ppm/rest/reports/IP+Protocols/" },



{ "name": "IP QoS", "uri": "http://ppm-cls-vm05.cisco.com:4440/ppm/rest/reports/IP+QoS/" }, { "name": "IP SLA", "uri": "http://ppm-cls-vm05.cisco.com:4440/ppm/rest/reports/IP+SLA/" }, { "name": "Mobile IOS Statistics", "uri": "http://ppm-cls-vm05.cisco.com:4440/ppm/rest/reports/Mobile+IOS+Statistics/" }, { "name": "Mobile StarOS Statistics", "uri": "http://ppm-cls-vm05.cisco.com:4440/ppm/rest/reports/Mobile+StarOS+Statistics/" }, { "name": "Resources", "uri": "http://ppm-cls-vm05.cisco.com:4440/ppm/rest/reports/Resources/" }, { "name": "Security", "uri": "http://ppm-cls-vm05.cisco.com:4440/ppm/rest/reports/Security/" }, { "name": "Transport Statistics", "uri": "http://ppm-cls-vm05.cisco.com:4440/ppm/rest/reports/Transport+Statistics/" }, { "name": "Video Broadcast", "uri": "http://ppm-cls-vm05.cisco.com:4440/ppm/rest/reports/Video+Broadcast/" } ] } }

6.2.3 XML Table 27 - XML Request / Response Sample – List of Reports

Request / Response (XML) – List of Reports Request – Notice, the Accept header is set for “application/xml”. GET /ppm/rest/reports/ HTTP/1.1 Accept: application/xml Host: ppm-cls-vm05.cisco.com:4440 Connection: Keep-Alive User-Agent: RestClient-Tool Response HTTP/1.1 200 OK Transfer-Encoding: chunked Date: Wed, 09 May 2012 15:41:10 GMT Content-Type: application/xml;charset=UTF-8 Server: Apache-Coyote/1.1 Cache-Control: 3600 <?xml version="1.0" ?> <reports> <reportInfo> <name>Application Traffic</name> <uri>http://ppm-cls-vm05.cisco.com:4440/ppm/rest/reports/Application+Traffic/</uri> </reportInfo> <reportInfo> <name>Availability</name> <uri>http://ppm-cls-vm05.cisco.com:4440/ppm/rest/reports/Availability/</uri> </reportInfo> <reportInfo> <name>IP Protocols</name> <uri>http://ppm-cls-vm05.cisco.com:4440/ppm/rest/reports/IP+Protocols/</uri>



</reportInfo> <reportInfo> <name>IP QoS</name> <uri>http://ppm-cls-vm05.cisco.com:4440/ppm/rest/reports/IP+QoS/</uri> </reportInfo> <reportInfo> <name>IP SLA</name> <uri>http://ppm-cls-vm05.cisco.com:4440/ppm/rest/reports/IP+SLA/</uri> </reportInfo> <reportInfo> <name>Mobile IOS Statistics</name> <uri>http://ppm-cls-vm05.cisco.com:4440/ppm/rest/reports/Mobile+IOS+Statistics/</uri> </reportInfo> <reportInfo> <name>Mobile StarOS Statistics</name> <uri>http://ppm-cls-vm05.cisco.com:4440/ppm/rest/reports/Mobile+StarOS+Statistics/</uri> </reportInfo> <reportInfo> <name>Resources</name> <uri>http://ppm-cls-vm05.cisco.com:4440/ppm/rest/reports/Resources/</uri> </reportInfo> <reportInfo> <name>Security</name> <uri>http://ppm-cls-vm05.cisco.com:4440/ppm/rest/reports/Security/</uri> </reportInfo> <reportInfo> <name>Transport Statistics</name> <uri>http://ppm-cls-vm05.cisco.com:4440/ppm/rest/reports/Transport+Statistics/</uri> </reportInfo> <reportInfo> <name>Video Broadcast</name> <uri>http://ppm-cls-vm05.cisco.com:4440/ppm/rest/reports/Video+Broadcast/</uri> </reportInfo> </reports>

6.3 GET /reports/{category}../{reportName}

6.3.1 Description This API is used to retrieve a specific report from the Prime Performance Manager server. A parameter (sgmid, category, FQDN) can be used to constraint the reporting data returned.

Following is sample request for the “Interface Availability” network level report. Notice that if the Prime Performance Manager server has SSL enabled, you should also include the Authorization header.

Table 28 – HTTP Report Request Sample – “Interface Availability” Network Level Report

HTTP Request Sample – “Interface Availability” Network Level Report GET /ppm/rest/reports/Availability/Interfaces/Interface++Availability HTTP/1.1 Host: ppm-cls-vm05.cisco.com:4440 Connection: Keep-Alive User-Agent: RestClient-Tool

6.4 Report Samples Note

Also, note that the sample reports belo w may only show a subset of the entire report. In the report below you may see “ . . .” to indicate that further data is available for that report.

: The following samples were collected from a development server. hese samples are provided to illustrate the data structure of the different data format types: XML, JSON, CSV. The data provided by your server will likely be different.



6.4.1 CSV Table 29 - CSV Request / Response Sample – “Interface Availability” Network Level Report

Request / Response (CSV) - “Interface Availability” Network Level Report Request GET /ppm/rest/reports/Availability/Interfaces/Interface++Availability HTTP/1.1 Host: ppm-cls-vm05.cisco.com:4440 Connection: Keep-Alive User-Agent: RestClient-Tool Response – Notice only a portion of the report is being displayed HTTP/1.1 206 Partial Content Transfer-Encoding: chunked Date: Wed, 09 May 2012 16:20:42 GMT Content-Type: text/csv;charset=UTF-8 Server: Apache-Coyote/1.1 Content-Range: pages 1/18 Cache-Control: no-cache Device,Interface,Timestamp EDT,Interface Index,Interface Availability Percentage Down,Interface Availability Percentage Up,Interface Availability Percentage Timeout pdngw-s-sami30-1,EOBC0/0,2012-05-08T13:00-0400,1,0.0,100.0,0.0 pdngw-s-sami30-1,GigabitEthernet0/0,2012-05-08T13:00-0400,2,0.0,100.0,0.0 ems7606d,EMS7606E-GigabitEthernet4/5,2012-05-08T13:00-0400,5,0.0,100.0,0.0 ems7606d,GigabitEthernet4/10,2012-05-08T13:00-0400,10,0.0,100.0,0.0 . . . . . . . . bacdev1-cmts-1,GigabitEthernet0/3,2012-05-08T16:00-0400,3,0.0,100.0,0.0

6.4.2 JSON Table 30 - JSON Requ est / Response Sample – “Interface Availability” Network L evel Report

Request / Response (JSON) - “Interface Availability” Network L evel Report Request – Notice, the outputType query string parameter is set “json”. GET /ppm/rest/reports/Availability/Interfaces/Interface++Availability?outputType=json HTTP/1.1 Host: ppm-cls-vm05.cisco.com:4440 Connection: Keep-Alive User-Agent: RestClient-Tool Response HTTP/1.1 206 Partial Content Transfer-Encoding: chunked Date: Wed, 09 May 2012 16:26:11 GMT Content-Type: application/json;charset=UTF-8 Server: Apache-Coyote/1.1 Content-Range: pages 1/18 Cache-Control: no-cache { "report": { "reportHeaders": { "reportHeader": [ "Device", "Interface", "Timestamp EDT", "Interface Index", "Interface Availability Percentage Down", "Interface Availability Percentage Up", "Interface Availability Percentage Timeout" ] }, "reportData": { "reportDataItems": [ { "reportDataItem": [ "pdngw-s-sami30-1",



"EOBC0/0", "2012-05-08T13:00-0400", "1", "0.0", "100.0", "0.0" ] }, { "reportDataItem": [ "pdngw-s-sami30-1", "GigabitEthernet0/0", "2012-05-08T13:00-0400", "2", "0.0", "100.0", "0.0" ] }, { "reportDataItem": [ "ems7606d", "EMS7606E-GigabitEthernet4/5", "2012-05-08T13:00-0400", "5", "0.0", "100.0", "0.0" ] }, { "reportDataItem": [ "ems7606d", "GigabitEthernet4/10", "2012-05-08T13:00-0400", "10", "0.0", "100.0", "0.0" ] }, . . . . . . . . { "reportDataItem": [ "bacdev1-cmts-1", "GigabitEthernet0/3", "2012-05-08T16:00-0400", "3", "0.0", "100.0", "0.0" ] } ] } } }

6.4.3 XML Table 31 – XML Request / Response Sample - “Interface Availability” Network Level Report

Request / Response (XML) - “Interface Availability” Network Level Report Request – Notice, the outputType query string parameter is set “xml”. GET /ppm/rest/reports/Availability/Interfaces/Interface++Availability?outputType=xml HTTP/1.1 Host: ppm-cls-vm05.cisco.com:4440 Connection: Keep-Alive User-Agent: RestClient-Tool



Response HTTP/1.1 206 Partial Content Transfer-Encoding: chunked Date: Wed, 09 May 2012 16:22:25 GMT Content-Type: application/xml;charset=UTF-8 Server: Apache-Coyote/1.1 Content-Range: pages 1/18 Cache-Control: no-cache <?xml version="1.0" ?> <report> <reportHeaders> <reportHeader>Device</reportHeader> <reportHeader>Interface</reportHeader> <reportHeader>Timestamp EDT</reportHeader> <reportHeader>Interface Index</reportHeader> <reportHeader>Interface Availability Percentage Down</reportHeader> <reportHeader>Interface Availability Percentage Up</reportHeader> <reportHeader>Interface Availability Percentage Timeout</reportHeader> </reportHeaders> <reportData> <reportDataItems> <reportDataItem>pdngw-s-sami30-1</reportDataItem> <reportDataItem>EOBC0/0</reportDataItem> <reportDataItem>2012-05-08T13:00-0400</reportDataItem> <reportDataItem>1</reportDataItem> <reportDataItem>0.0</reportDataItem> <reportDataItem>100.0</reportDataItem> <reportDataItem>0.0</reportDataItem> </reportDataItems> <reportDataItems> <reportDataItem>pdngw-s-sami30-1</reportDataItem> <reportDataItem>GigabitEthernet0/0</reportDataItem> <reportDataItem>2012-05-08T13:00-0400</reportDataItem> <reportDataItem>2</reportDataItem> <reportDataItem>0.0</reportDataItem> <reportDataItem>100.0</reportDataItem> <reportDataItem>0.0</reportDataItem> </reportDataItems> <reportDataItems> <reportDataItem>ems7606d</reportDataItem> <reportDataItem>EMS7606E-GigabitEthernet4/5</reportDataItem> <reportDataItem>2012-05-08T13:00-0400</reportDataItem> <reportDataItem>5</reportDataItem> <reportDataItem>0.0</reportDataItem> <reportDataItem>100.0</reportDataItem> <reportDataItem>0.0</reportDataItem> </reportDataItems> <reportDataItems> <reportDataItem>ems7606d</reportDataItem> <reportDataItem>GigabitEthernet4/10</reportDataItem> <reportDataItem>2012-05-08T13:00-0400</reportDataItem> <reportDataItem>10</reportDataItem> <reportDataItem>0.0</reportDataItem> <reportDataItem>100.0</reportDataItem> <reportDataItem>0.0</reportDataItem> </reportDataItems> . . . . . . <reportDataItems> <reportDataItem>bacdev1-cmts-1</reportDataItem> <reportDataItem>GigabitEthernet0/3</reportDataItem> <reportDataItem>2012-05-08T16:00-0400</reportDataItem> <reportDataItem>3</reportDataItem> <reportDataItem>0.0</reportDataItem> <reportDataItem>100.0</reportDataItem> <reportDataItem>0.0</reportDataItem> </reportDataItems> </reportData> </report>



7 Pagination The reports retrieved from the REST API has a upper limit set to 1000 records per page unless modified by the “maxPageSize” parameter. If a report has more than 1000 records, the report is divided into pages. The first REST response will contain the first 1000 records along with a “Content-Range” header (refer to HTTP Response Header s section of this document).

When the report is broken into multiple pages, you need to pass the “pageIndex” parameter to navigate to the next pages. In this case, you need to pass the pageIndex parameter to go to the next pages. You should rely on the returned “Content-Range” value to determine which page is returned, an d how many pages the report contains.

The following table shows a report sample that displays the “pageIndex” request parameter and a “Content-Range” header response.

Table 32 - CSV Request / Response Sample Showing Pagination (Content-Range Head er)

Request GET /ppm/rest/reports/Availability/Interfaces/Interface++Availability?pageIndex=3 HTTP/1.1 Host: ppm-cls-vm05.cisco.com:4440 Connection: Keep-Alive User-Agent: RestClient-Tool Response – Notice the “Content-Range” header indicating pagination. HTTP/1.1 206 Partial Content Transfer-Encoding: chunked Date: Wed, 28 Mar 2012 21:38:10 GMT Content-Type: text/csv;charset=UTF-8 Server: Apache-Coyote/1.1 Content-Range: pages 3/11

Cache-Control: no-cache Device, Interface, Timestamp EDT, Interface Index,Interface Availability Percentage Down,Interface Availability Percentage Up,Interface Availability Percentage Timeout spgw-o-sami03,testing-GigabitEthernet0/0,04/23/2012 10:00:00,2,0.0,100.0,0.0 spgw-o-sami03,Loopback50,04/23/2012 10:00:00,5,0.0,100.0,0.0 spgw-o-sami03,mwtm_test1-GigabitEthernet0/0.10,04/23/2012 10:00:00,6,0.0,100.0,0.0 spgw-o-sami03,NVI0,04/23/2012 10:00:00,7,0.0,100.0,0.0 NAM-172.20.110.196,MGMT PORT-MGMT PORT,04/23/2012 10:00:00,1,0.0,100.0,0.0 NAM-172.20.110.196,DATA PORT 1-DATA PORT 1,04/23/2012 10:00:00,2,0.0,100.0,0.0 NAM-172.20.110.196,DATA PORT 2-DATA PORT 2,04/23/2012 10:00:00,3,0.0,100.0,0.0 NAM-172.20.110.196,NDE-172.20.122.2-ID-520-NDE-172.20.122.2-ID-520,04/23/2012 10:00:00,7,0.0,100.0,0.0 NAM-172.20.110.196,NDE-172.20.122.2-ID-0-NDE-172.20.122.2-ID-0,04/23/2012

10:00:00,8,0.0,100.0,0.0 . . . .

. . . .

8 References Fielding, R. T . “Architectural Styles and the Design of Network-based Software Architectures” . Ph.D. dissertation, University of California, Irvine, 2000.

Richardson, L. & Ruby, S. (2007). RESTful Web Services. Sebastopol, CA : O'Reilly Media.

Bernes-Lee, T ., Fielding, R. T ., et al. Uniform Resource Identifier (URI): Generic Syntax, RFC 3986, RFC Editor, 2005 (http://www.rfc-editor.org/rfc/rfc3986.txt).

Request for Comments (RFC) http://www.ietf.org/rfc.html

http://www.ietf.org/rfc.html�



9 Glossary API: Application Programming Interface

H TTP: Hypertext Transfer Protocol

H TTPS: Hypertext Transfer Protocol over Transport Layer Security (TLS)

JSO N: JavaScript Object Notation

PPM: Prime Performance Manager

RES T: Representational State Transfer (REST)

RFC : Request for Comment

SSL: Secure Socket Layer

XML: Extensible Markup Lan guage

cisco prime performance manager rest api guide, 1...prime performance manager 1.2 user guide and...

Documents