Cisco Prime Performance Manager REST API Guide
Cisco Prime Performance Manager 1.2
REST API Guide
June 15, 2012
Copyright 2012 Cis co Systems
-1-
Cisco Prime Performance Manager REST API Guide
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
Copyright 2012 Cis co Systems
-2-
Cisco Prime Performance Manager REST API Guide
5.7.11
6
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
REST APIs ...................................................................................................................................18
6.1
GET /reports/{category}.. .................................................................................................... 18
6.1.1
6.2
Description ..................................................................................................................... 18
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
6.4
Description ..................................................................................................................... 21
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
T his document describe s the Cisco Prime Performance Manager Representational State T ransfer (REST )
API used to retrieve reports data from Prime Performance Manager. T he REST API is implemented as a
we b service front-end component on the Prime Performance Manager gateway. T he API allows
applications to retrieve performance data from the gateway using HT T P(s) GET requests with the URLs
specified in this doc ument.
T he data provided by the REST API can be formatted as XML (eXtensible Markup Langua ge), JSON
(Java Script Object Notation), or CSV (comma separated value). T he report data format is based on the
reque st HTT P Accept Header or the value of the “ outputT ype” query string parameter. If no specific data
type is requested, the report data defaults to CSV.
Copyright 2012 Cis co Systems
-3-
Cisco Prime Performance Manager REST API Guide
2 Assumptions
2.1 Audience
T his document is intended for developers who wish to implement the network management REST Ful
client to consume performance reporting data from the Prime Performance Manager application. T he
audience is a ssumed to be familiar with RE ST ful we b service s and the HTTP protocol.
2.2 HTTP Version
T he Reports REST API embraces several aspects of the HTT P standards, includin g some headers, HT T P
verbs, and status code s. T he REST API uses status codes that are only supported in the HTTP/1.1 version.
T herefore, it is expected that the client consuming this API complies with these HTT P/1.1 features.
2.3 SSL and HTTP
T his 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 HTT P/SSL protocol and have the
Prime Performance Manager SSL public certificate installed on the client’s thrust store file.
2.4 Read Only API
T his REST API is use d for reading network performance reporting data. It supports the HTTP GET
method which does not affect the state of the resource being querie d in the server.
2.5 Versioning
T he Prime Performance Manager Reports REST API complies with the following versioning r ule:
elements may be adde d when releasing a ne w version, but they may never be removed. A new release of
this API is expected to be down war d compatible with a previous version. An older version of this Reports
RE ST API might appear to the client as if some elements were removed.
3 Prime Performance Manager REST API
Installation
T his 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 a uthentication
are not provided, as that pertains to the Prime Performance Manager server.
T he Reports REST API is a Prime Performance Manager gateway component. All code needed to run and
test the Reports REST API is include d in the Prime Performance Manager installation. After you install
Prime Performance Manager, no additional Prime Performance Manager Reports RE ST API
configuration is needed.
4 Reports Default Time Durations
T he reporting data returned from the PPM REST API has the durations shown in the following table,
base d off the interval (intervalTypeKey parameter). If the startDate and endDate parameters are provided
Copyright 2012 Cis co Systems
-4-
Cisco Prime Performance Manager REST API Guide
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_MINUT E
Last 6 hours
15 min 1
QUART ER_HOUR
Last 12 hours
Hourly 2
HOUR
Last 24 hours
Daily
DAY
Last 30 days
Weekly
WEEK
Last 6 months
Monthly
MONT H
Last 1 year
5 REST API Components
5.1 Content-Type
T he report data provided by the RE ST API can be formatted as XML, JSON, or CSV. T he data format is
base d on the values of the incoming HTTP Accept header or the “ outputT ype” 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”.
T he response content-type may be specified usin g either the HTTP request “ Accept” header or the
“ outputT ype” parameter. T he “ outputT ype” parameter has precedence over the “ Accept” header. If
neither the “outputT ype” parameter nor the “ Accept” header (or if the Accept header found matches */*),
the content-type defaults to “text/csv”.
T he following “ outputT ype” parameter values can be use d:
For CSV: “ csv”
For JSON: “ json”
For XML: “ xml”
When using the HTTP “ Accept” header, the following can be use d:
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 sp eci fic repo rts are by default ren dered as 15 min interval reports. A node report requires either an FQDN
node or sgmid valu e to be pro vided as a qu ery string param eter in the REST API URL.
2
Network level reports are by default rend ered as hourly reports. Net work l evel reports consist of data for the top
node el em ents. It is the default repo rt wh en no FQDN or sgmid query string paramet er is provided in the REST API
URL.
Copyright 2012 Cis co Systems
-5-
Cisco Prime Performance Manager REST API Guide
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
T his Reports RE ST API defaults all the responses to the “ UT F-8” charset encoding, irrespective of the
reque sted charset sent.
5.3 URI Syntax
T he REST API calling URI syntax is defined as follo ws:
Table 2 – URL Syntax
URL Syntax
{scheme }://{host}:{port}/ppm/re st/re ports/{resource }?{parame te rs=…}..
Table 3 – URL Parts
URL Parts
Sample Value
Description
sche me
http or https
Use https when Prime Performance
Manager SSL is enabled; otherwise, it
should be http.
Host
For example: “ppmclean.cisco.com”
T he host name assigne d to the Prime
Performance Manager gateway server
Note: use your own domain name
above.
Copyright 2012 Cis co Systems
-6-
Cisco Prime Performance Manager REST API Guide
Port
For example: 4440
HTT P port number assigned to the Prime
Performance Manager gateway server.
Note that the same port number may be
use d when Prime Performance Manager is
running in SSL enabled mo de.
Path pre fix
/ppm/rest/
All the REST API paths must be prefixed
with this value. T his 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.
Re source s
/{category}..
A collection resource containing listing
of all report category, sub-categories an d
corresponding report names URIs in the
system.
/{category}../{reportName}
A document resource containing the
report information (data) itself which can
be filtered using query string parameters.
outputType, FQDN,sgmid,
startDate, endDate,
durationSelect, …
Refer to Query String Parameters
Parame te rs
5.4 HTTP Verb
T he Reports REST API is read-only. It only supports the HTT P GET verb. The following table sho ws an
example of a URL and corresponding GET reque st 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}..
T he REST API provides a directory listing of all the report categories, subcategories and report names.
T his type of resource is generally known as a colle ction 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 use d to identify a group of reports. Categories consist of
Copyright 2012 Cis co Systems
-7-
Cisco Prime Performance Manager REST API Guide
subcategories that form a hierarchical path to various reports in the system. T herefore, 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
/re ports/{cate gory}..
T he list of reports for that category. An empty {category}
implies the root category that shows all the top report
categories.
List all reports subcategories and reports (if any) under the
“ Availability” category.
List all reports subcategories and reports (if any) under the
“ ICMP Ping” category.
Note: “ +” (plus-sign) represents a space in the URL.
/re ports /Availability
/re ports/Availability/ICMP+Ping
5.5.2 Report – Document Resource
Example: GET /ppm/rest/reports/{category}../{reportName}?{query String}
T he REST API provides data about various sy stem reports. T his 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 unique ly
identified by a {reportName} and a specific {category}.
Notice that {query String} parameters (FQDN, sgmid, startDate, endDate, …) are use d to filter out the
reporting data for a given the report document resource.
Table 6 – Report Ex ample
Resource Name
Description
/re ports/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
T he URL must be encoded accor ding to the Internet URL standards ( RFC 3986). Some characters are not
considere d safe for URL use. T hese must be properly converted to their encoded counterpart prior to URL
reque st submission. For safety, always encode the parameter values before you submit the reque st. For
further information, see to the Internet standards (RFC 3986).
T he server side of the REST API always decode s the passed in parameter values accordin g to RFC 3986
standards. T herefore, the client side must always encode the parameter values usin g the same standards.
Note: T he “ +” (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 encode d form “ %2B”.
5.7 Query String Parameters
T he following table s sho w the RE ST API request parameters. The REST API is usin g a subset of the
HTT P request parameters found in the Prime Performance Manager we b base d application. T his allows
Copyright 2012 Cis co Systems
-8-
Cisco Prime Performance Manager REST API Guide
the REST API and Prime Performance Manager we b ba se d application to have consistent names. T his
also allo ws the same value s used in the we b base d GUI to be passe d to the REST API.
Note:
-
Parame te r names/value s are case -se nsitive.
Parameter values should be encode d to escape non-safe HTT P characters.
Some parameters are mutually exclusive.
5.7.1 FQDN
Table 7 – FQ DN Parameter
Para meter
FQ DN
Notes
The FQDN (Fully Quali fi ed Domain Nam e) value as defi ned in the Prim e Performan ce
Manager Server
Format:
Nod e=<host or IP>,<other keys as defined in the corres ponding report XM L file>
Following are exampl es of valid formatt ed FQDN values.
Node=em1941kbf. cis co.com
Nod e=10.74.125.210
Node=em1941kbf. cis co.com,i fDescr=FastEthernet0/0
Nod e=10.74.125.210,CPUSlot=0,CPUNum=0,processorIndex=1
Refer to your Prime Performance Manager ser ver or network to det er mine your own
FQDN values.
Addition al Notes
1) Only supported in the “ GET /reports/{ cat egory}../{report Nam e} ” requests.
2) If an FQDN or sgmid is not provided, the REST API defaults to a top network level report. A network lev el
repo rt consists of information for the top sampl es in that report met ric.
3) Refer to the Prim e Perform ance M anager docum entation for more inform ation about net work level repo rts.
5.7.2 sgmid
Table 8 – sgmid Parameter
Para meter
sgmid
Notes
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) bel ow.
Refer to your Prime Performance Manager ser ver or network to det er mine your own
FQDN values
Additional Notes
• Only suppo rted in the “ GET /reports/{ cat egory}../{report Nam e} ” requests.
• If an FQDN or sgmid is not provided, the REST API defaults to a top network level report. A network lev el
repo rt consists of information for the top sampl es in that report met ric. Refer to the Prim e Performance
Man ager do cum entation for mo re in form ation about net work-level reports.
• For consist ency with the Prim e Perform ance M anager web bas ed application an “ sgmid” equal to -1m eans
a network level repo rt. However, this “ sgmid” param eter value is not requi red as a network level report is
alread y assum ed wh en “ FQDN” and “ sgmid” are not given.
Copyright 2012 Cis co Systems
-9-
Cisco Prime Performance Manager REST API Guide
5.7.3 startDate
Table 9 – startDate Parameter
Para meter
startDate
Notes
The start dat e for the reporting data.
Format:
yyyy-MM-ddTHH:mm Z
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: hou r in day (0 -23)
mm: minute in hour (0-59)
Z: time zone represent ed as follows (+/ -)HHmm
“+” to add or “ -“ to subtract the “ HHmm” from the GMT time.
Exampl es:
2012-3-23T12:30+ 0800
2012-12-2 3T2:05+0800
Note: “+” needs to be encoded to “% 2B” prior to being sent on the HTTP r equ est.
Addition al Notes
• Only suppo rted in the “ GET /reports/{ cat egory}../{report Nam e} ” requests.
• The “ startDat e”/“ endDat e” and “ durationSel ect” paramet ers are mutually exclusi ve.
• 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 giv en, their tim ezone must mat ch. For exampl e:
startDat e is not given.
endDat e=”2012-03-23T12:30+080 0”
duratio n=”l ast24 Hours ”
interv alTypeKey=”HOUR”
The startDate is 24 hours less than the “ endDat e”; that is “ 2012-03-22T12:30+0800”
• The “ startDat e” may be cal cul ated to be a dat e in the future. In that cas e, keep in mind that no reporting
in form ation is availabl e in the system for a future dat e.
• If “ startDat e” and “ endDat e” are not given, the current server tim e is used for the “ endDat e”. The
“ startDate” is cal culat ed by subt racting the “ durationSel ect ” from the current time. In this case, the
date/tim es will all be set according to the server timezone settings.
• Provide either the start or end d ate with proper GMT offset to ens ure the reporting dat a received are in the
exp ect ed timezone.
5.7.4 endDate
Table 10 – endDate Parameter
Para meter
endDate
Notes
The end dat e for the reporting dat a.
Format:
yyyy-MM-ddTHH:mm Z
where,
Copyright 2012 Cis co Systems
- 10 -
Cisco Prime Performance Manager REST API Guide
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: hou r in day (0-23)
mm: minute in hour (0 -59)
Z: time zone represent ed as follows (+/ -)HHmm
“+” to add or “ -“ to subtract the “ HHmm” from the GMT time.
Exampl e:
2012-04-2 3T02:30+0800
Note: “+” needs to be encoded to “% 2B” prior to being sent on the HTTP r equ est.
Addition al Notes
• Only suppo rted in the “ GET /reports/{ cat egory}../{report Nam e} ” requests.
• The “ startDat e”/“ endDat e” and “ durationSel ect” paramet ers are mutually exclusi ve.
• If the “ endDate” is not given, it will default to the cal culat ed val ue based on “ durationSelect ” and
“ startDate” (or system time i f “ startDat e” is not given).
• If both startDate and end Date are giv en, their tim ezone must mat ch. For exampl e,
end Dat e is not given.
startDat e=”2012-03-2 2T12:30+0800”
duratio n=”l ast24 Hours ”
interv alTypeKey=”HOUR”
The endDate is 24 hou rs plus the “ startDat e”; that is “ 2012-03-23T12:30+0800”
• The “ endDate” may be calcul ated to b e a dat e in the future. In that case, the us er should keep in mind that
no rep orting in form ation is av ailabl e in the system for a fut ure dat e.
• If “ startDat e” and “ endDat e” are not given, the REST API will det ermine the “ startDat e” and “ endDate”
using the timezone set in the Prime Perform ance M anager 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 p rovid e eith er th e start or end dat e with proper GMT offs et to ensure the reporting data
received are in the expect ed timezone.
5.7.5 durationSelect
Table 11 – durationSel ect Parameter
Para meter
durationSel ect
Notes
The duration int erval used for the reporting data. Possible values:
last5Years
last1Year
last6Months
last90Days
last60Days
last30Days
last21Days
last7Days
last3Days
lastDay or last2 4Hours
last12Hours
last6Ho urs
lastHour
Addition al Notes
• Only suppo rted in the “ GET /reports/{ cat egory}../{report Nam e} ” requests.
• The “ startDat e”/“ endDat e” and “ durationSel ect” paramet ers are mutually exclusi ve.
Copyright 2012 Cis co Systems
- 11 -
Cisco Prime Performance Manager REST API Guide
•
•
•
The default valu e is last24Hours fo r network level report, unless the “ intervalTypeKey” param eter is
provid ed (refer to do cum ent section 4 Reports Default Time Durations).
The default value is last12Hours fo r a speci fi c node report, unless the “ intervalTypeKey” paramet er is
provid ed (refer to do cum ent section 4 Reports Default Time Durations).
The durationS elect must be greater than intervalTypeKey.
Default v alues for “ durationSel ect” are b as ed on “ intervalTypeKey” -- refer to document s ection 4 Reports Default
Time Duratio ns.
5.7.6 intervalTypeKey
Table 12 – intervalTypeK ey Parameter
Para meter
intervalTypeK ey
Notes
The average interval type for the measurements in the reporting dat a.
Possible values:
FIVE_MINUTE
QUARTER_HOUR
HOUR
DAY
WEEK
MONTH
Addition al Notes
• Only suppo rted in the “ GET /reports/{ cat egory}../{report Nam e} ” requests.
• The default is HOUR for n etwo rk level reports; that is, when “ FQDN” or “ sgmid” are not given.
The default is QUARTER_HOUR for a node level report; that is, either “ FQDN” or “ sgmid” is given.
5.7.7 pageIndex
Table 13 – pageIndex Parameter
Para meter
pageIndex
Notes
The repo rt pag e number being requested for multi-page reports.
Format: a positive int eger number greater than 0.
Addition al Notes
• Only suppo rted in the “ GET /reports/{ cat egory}../{report Nam e} ” requests.
5.7.8 maxPageSize
Table 14 – maxPageSi ze Parameter
Para meter
maxPageSi ze
Notes
The total number of records in the response.
Format: a positive integer num ber great er than 0.
Addition al Notes
• Only suppo rted in the “ GET /reports/{ cat egory}../{report Nam e} ” requests.
• The default is 1000.
• This param eter represents the maxim um number of records found in the report, and not on the page.
• The paramet er nam e was m aitained to be consistent with the sam e param et er name us ed in the Prime
Perform ance M anager web bas ed application.
Copyright 2012 Cis co Systems
- 12 -
Cisco Prime Performance Manager REST API Guide
5.7.9 outputType
Table 15 – outputType Pa ra meter
Para meter
outputType
Notes
The content-type det ermines the expect ed format of the dat a in the
response. This paramet er, when provided, overrides the value defin ed in
the HTTP “ Accept ” header.
Possible values:
csv
xml
json
Addition al Notes
• This param eter is support ed in all requests.
• The default value is csv.
5.7.10 csvHeader
Table 16 – csvHeader Parameter
Para meter
csvH eader
Notes
The csvHeader may be used to disable headers in CSV respons es. By
default CSV cont ent contains headers in the first line. If the us er do es
not want to see headers in the fi rst line, this paramet er shoul d be set to
“ false”.
Possible values:
true (default)
fals e
Addition al Notes
• This param eter is support ed in all requests.
• The default value is true.
5.7.11 showAllReports
Table 17 – showAllReports Pa ra meter
Para meter
showAllRepo rts
Notes
The showAllR eports may be us ed to list all reports within a given
cat egory or sub-category. This param et er only applies when listing the
reports in the Prime Perform ance M anager system.
Possible values:
This param eter is an empty param eter. It does not accept a value.
Addition al Notes
• This param eter is only applicabl e to generate a listing of reports.
• There is no default value, as this paramet er stands on its own
Copyright 2012 Cis co Systems
- 13 -
Cisco Prime Performance Manager REST API Guide
5.8 REST Parameter Rules
T he following re que st parameters rules are enforced by the REST API.
•
Only parameters identified in the Reque st 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 durationSele ct are mutually exclusive.
•
endDate must be greater than startDate .
•
durationSele ct must be greater than inte rvalType Ke y.
•
showAllRe ports must not contain a value.
5.9 HTTP Request Headers
T he following table has the HTT P Request headers supported.
5.9.1 Accept
Table 18 – Accep t HTTP Header
Header Na me
Accep t
Notes
The requested cont ent-type for the response. This header indicat es to the REST API
server the medi a type of the respons e expected by the client. When this header is
pres ent the REST API will attem pt to respond to the client using that medi a type;
unless, that cont ent -type is not supported by the REST API for the request ed resou rce.
Note th at the medi a type can be overriden by the outputType paramet er.
Also, note that the REST API currently does not pars e/process quality factor “ qvalues”
scal e (0 to 1) paramet ers that may be found on the accept header. As per RFC 2616
(14.1 Accept), the “ qvalue” is a param eter beginning with the l etter “ q” that may b e
pres ent on the accept header to indicate the rel ative preference for a speci fi c medi a
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 suppo rted values are:
text/csv
application/xml
application/json
Note: If no Accept header is found, or if “*/*”, the respons e will default to the text/ csv
media t ype.
Addition al Notes:
Copyright 2012 Cis co Systems
- 14 -
Cisco Prime Performance Manager REST API Guide
•
•
•
The outputType param et er ov errides this header.
Refer to Content -Type for more in fo rm ation.
The default cont ent-type is text/ csv.
5.9.2 Authorization
Table 19 – Authori zati on HTTP header
Header Na me
Notes
Authori za tion
This is a request header that should be s ent to the REST API when the underlying
Prime Performance Manager s erver has user access enabl ed. The speci fics of how this
header should b e form atted 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.
Addition al Notes:
• Veri fy that this header is sent with the request i f Prim e Performance Manager has user access enabl ed
• The userId and p assword d efin ed in the Prim e Perform ance M anager server must be base64 encoded and
added to the head er as d efin ed in the HTTP standards.
5.10 HTTP Response Headers
T he following table shows the HTTP Response headers supported.
Table 20 – HTTP Response H eaders
Header Name
Sample Value
Description
Allow
For example, “ GET ”
T his header is generated along
with status code “ 405” in
response to request with a
method (HEAD, POST , PUT ,
DELET E) that is not supported
for that resource.
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 cache d
by the client. And the max-age
value tells the client how long in
seconds the response should be
cached.
Conte nt-Type
For example. “ application/xml;charset=UT F8”
T he content-type of the response
followe d by the charset encoding.
Date
For example. “ Date
20:29:02 GMT ”
T he date the response was
created.
WWWAuthenticate
“ Basic realm=RE ST Sec ureArea”
(HTTP/1.1)
Cache-Control
(HTTP/1.1)
Copyright 2012 Cis co Systems
Fri, 27 Jan 2012
- 15 -
T his header is sent back to the
client when Prime Performance
Cisco Prime Performance Manager REST API Guide
Manager has user access
(authentication) enabled, and the
system failed to authenticate the
user’s re quest (see the
Authorization
Reque st header above). T his
response header conforms to the
HTT P Basic WWW-Authenticate
header define d in HT TP 1.0
standards.
Conte nt-Range
pages <pa ge num ber>/<total pages
For example. “ pages 2/10”
T his response header is sent back
when there is more than one page
available for the requested report.
In the example the current response contains
page 2 of a report that has 10 pages total.
5.11 HTTP Status Code
T he following table shows the HTTP Status codes supported.
Table 21 – HTTP Status Codes
Status Code
Description
200
OK response. T he request was correctly processed, and a response with a
content body was produce d.
204
No content found. That is, the request wa s a valid re quest; 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. T his 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 Re quest. T his happens when the request has an invalid parameter, or it is
missin g a require d parameter. Or it could also be the case when the requested
resource path is not in the expected syntax.
401
Authentication Failed. T his status code is generated when the Prime
Performance Manager server is running with user acce ss (a uthentication)
enable d, and the RE ST API server was una ble to authenticate the user.
404
Reso urce Not Found. T his status code is generated when the requested reso urce
does not exist in the Prime Performance Manager RE ST 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. T his status code is generated when the requested method
(HEAD, POST , PUT or DELET E) is not supported for that resource.
Copyright 2012 Cis co Systems
- 16 -
Cisco Prime Performance Manager REST API Guide
406
Not Acceptable. T his status code is generated when the “ Accept” header sent in
the request is not supported by the REST API.
415
Unsupported Media T ype. T his 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. T his 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 Respons e Sample – Invalid HTTP Verb
Reques t / Error Response (CSV) - Invalid HTTP Verb: POST
Reques t
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
Respons e
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 Respons e Sample - Invalid HTTP Verb
Reques t / Error Response (Json) – Invalid HTTP Verb: POST
Reques t – 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
Respons e
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",
Copyright 2012 Cis co Systems
- 17 -
Cisco Prime Performance Manager REST API Guide
"message": "HTTP method [POST] is not supported."
}
}
Table 24 - XML Reques t / Error Response Sample - Invalid HTTP Verb
Reques t / Error Response (XML) – Invalid HTTP Verb: POST
Reques t – 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
Respons e
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
T he APIs are composed of a GET URI + reso urce + parameters (or parameters) combination.
6.1 GET /reports/{category}..
6.1.1 Description
T his 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.
T he following table shows a sample re que st for the top level report categories. Notice that if the Prime
Performance Manager server has SSL enable d, you should a lso include the Authorization header.
Table 25 - – HTTP List of Reports Reques t Sample – Top Level Category
HTTP Reques t 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: T he following samples were colle cted from a development server. T hese samples are provided to
illustrate the data structure of the different data format types: XML, JSON, CSV. T he data provided by
your server will likely be different.
Copyright 2012 Cis co Systems
- 18 -
Cisco Prime Performance Manager REST API Guide
6.2.1 CSV
Table 22 - CSV Request / Response Sampl e – List of Reports
Reques t / Respons e (CSV) – List of Reports
Reques t
GET /ppm/rest/reports/ HTTP/1.1
Host: ppm-cls-vm05.cisco.com:4440
Connection: Keep-Alive
User-Agent: RestClient-Tool
Respons e
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-clsvm05.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 / Respons e Sampl e – List of Reports
Reques t / Respons e (JSON) – List of Reports
Reques t – 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
Respons e
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/"
},
Copyright 2012 Cis co Systems
- 19 -
Cisco Prime Performance Manager REST API Guide
{
"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 Reques t / Respons e Sample – List of Reports
Reques t / Respons e (XML) – List of Reports
Reques t – 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
Respons e
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>
Copyright 2012 Cis co Systems
- 20 -
Cisco Prime Performance Manager REST API Guide
</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
T his API is used to retrieve a specific report from the Prime Performance Manager server. A parameter
(sgmid, category, FQDN) can be use d to constraint the reporting data returned.
Following is sample reque st 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 Reques t Sample – “Interface Av ailability” 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: T he following samples were colle cted from a development server. hese samples are provided to
illustrate the data structure of the different data format types: XML, JSON, CSV. T he data provided by
your server will likely be different.
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.
Copyright 2012 Cis co Systems
- 21 -
Cisco Prime Performance Manager REST API Guide
6.4.1 CSV
Table 29 - CSV Request / Response Sampl e – “Interface Availability” Network Level Report
Reques t / Respons e (CSV) - “Interface Availability” Network Level Report
Reques t
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
Respons e – 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 / Respons e Sampl e – “Interface Availability” Network L evel Report
Reques t / Respons e (JSON) - “Interface Availability” Network L evel Report
Reques t – Notice, the outputTyp e quer y string paramet er 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
Respons e
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",
Copyright 2012 Cis co Systems
- 22 -
Cisco Prime Performance Manager REST API Guide
"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 Reques t / Response Sample - “Interface Availability” Network Level Report
Reques t / Respons e (XML) - “Interface Availability” Network Level Report
Reques t – Notice, the outputTyp e quer y string paramet er 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
Copyright 2012 Cis co Systems
- 23 -
Cisco Prime Performance Manager REST API Guide
Respons e
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>
Copyright 2012 Cis co Systems
- 24 -
Cisco Prime Performance Manager REST API Guide
7 Pagination
T he reports retrieved from the REST API has a upper limit set to 1000 records per page unless modified
by the “ maxPage Size” parameter. If a report has more than 1000 records, the report is divide d into pages.
T he first REST response will contain the first 1000 records along with a “ Content-Range” header (refer to
HTT P 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.
T he following table shows a report sample that displays the “ pageIndex” request parameter and a
“ Content-Range” header response.
Table 32 - CSV Request / Response Sampl e 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-base d Software Architectures” . Ph.D.
dissertation, University of California, Irvine, 2000.
Richardson, L. & Ruby, S. (2007). RESTful Web Service s. Se bastopol, 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-e ditor.org/rfc/rfc3986.txt).
Reque st for Comments (RFC) http://www.ietf.org/rfc.html
Copyright 2012 Cis co Systems
- 25 -
Cisco Prime Performance Manager REST API Guide
9 Glossary
API: Application Programming Interface
H TTP: Hypertext T ransfer Protocol
H TTPS: Hypertext T ransfer Protocol over T ransport Layer Security (T LS)
JSO N: JavaScript Object Notation
PPM: Prime Performance Manager
RES T: Representational State Transfer (REST )
RFC: Re quest for Comment
SSL: Sec ure Socket Layer
XML: Extensible Markup Lan gua ge
Copyright 2012 Cis co Systems
- 26 -