CA Spectrum®

Web Services API Reference Guide

Release 9.3
This Documentation, which includes embedded help systems and electronically distributed materials, (hereinafter referred to
as the “Documentation”) is for your informational purposes only and is subject to change or withdrawal by CA at any time.
This Documentation may not be copied, transferred, reproduced, disclosed, modified or duplicated, in whole or in part, without
the prior written consent of CA. This Documentation is confidential and proprietary information of CA and may not be disclosed
by you or used for any purpose other than as may be permitted in (i) a separate agreement between you and CA governing
your use of the CA software to which the Documentation relates; or (ii) a separate confidentiality agreement between you and
CA.
Notwithstanding the foregoing, if you are a licensed user of the software product(s) addressed in the Documentation, you may
print or otherwise make available a reasonable number of copies of the Documentation for internal use by you and your
employees in connection with that software, provided that all CA copyright notices and legends are affixed to each reproduced
copy.
The right to print or otherwise make available copies of the Documentation is limited to the period during which the applicable
license for such software remains in full force and effect. Should the license terminate for any reason, it is your responsibility to
certify in writing to CA that all copies and partial copies of the Documentation have been returned to CA or destroyed.
TO THE EXTENT PERMITTED BY APPLICABLE LAW, CA PROVIDES THIS DOCUMENTATION “AS IS” WITHOUT WARRANTY OF ANY
KIND, INCLUDING WITHOUT LIMITATION, ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
PURPOSE, OR NONINFRINGEMENT. IN NO EVENT WILL CA BE LIABLE TO YOU OR ANY THIRD PARTY FOR ANY LOSS OR DAMAGE,
DIRECT OR INDIRECT, FROM THE USE OF THIS DOCUMENTATION, INCLUDING WITHOUT LIMITATION, LOST PROFITS, LOST
INVESTMENT, BUSINESS INTERRUPTION, GOODWILL, OR LOST DATA, EVEN IF CA IS EXPRESSLY ADVISED IN ADVANCE OF THE
POSSIBILITY OF SUCH LOSS OR DAMAGE.
The use of any software product referenced in the Documentation is governed by the applicable license agreement and such
license agreement is not modified in any way by the terms of this notice.
The manufacturer of this Documentation is CA.
Provided with “Restricted Rights.” Use, duplication or disclosure by the United States Government is subject to the restrictions
set forth in FAR Sections 12.212, 52.227-14, and 52.227-19(c)(1) - (2) and DFARS Section 252.227-7014(b)(3), as applicable, or
their successors.
Copyright © 2013 CA. All rights reserved. All trademarks, trade names, service marks, and logos referenced herein belong to
their respective companies.
CA Technologies Product References
This document references the following products:
■ CA Spectrum® (CA Spectrum)
■ CA Spectrum® Modeling Gateway Toolkit (Modeling Gateway)
■ CA Spectrum® Southbound Gateway Toolkit (Southbound Gateway)

Contact CA Technologies
Contact CA Support

For your convenience, CA Technologies provides one site where you can access the
information that you need for your Home Office, Small Business, and Enterprise CA
Technologies products. At http://ca.com/support, you can access the following
resources:
■ Online and telephone contact information for technical assistance and customer
services
■ Information about user communities and forums
■ Product and documentation downloads
■ CA Support policies and guidelines
■ Other helpful resources appropriate for your product

Providing Feedback About Product Documentation

If you have comments or questions about CA Technologies product documentation, you

can send a message to [email protected].

To provide feedback about CA Technologies product documentation, complete our

short customer survey which is available on the CA Support website at
http://ca.com/docs.
Contents
Chapter 1: Introduction 9
About the CA Spectrum Web Services API ................................................................................................................... 9
REST Architecture ....................................................................................................................................................... 10
Supported Technologies............................................................................................................................................. 10
CA Spectrum Web Services API and OneClick ............................................................................................................ 11
Performance Considerations ...................................................................................................................................... 12
Limitations .................................................................................................................................................................. 12

Chapter 2: Working with the CA Spectrum Web Services API 13

How to Use the CA Spectrum Web Services API ........................................................................................................ 13
Requests ..................................................................................................................................................................... 13
Request Types ..................................................................................................................................................... 14
General URL Parameters ..................................................................................................................................... 15
Security ............................................................................................................................................................... 15
Responses................................................................................................................................................................... 16
Web Application Description Language (WADL) URL ................................................................................................. 18
CA Spectrum Web Services API Files .......................................................................................................................... 18
XML Schema Definitions............................................................................................................................................. 18

Chapter 3: REST Operations (Verbs) 21

Chapter 4: RESTful Resources (Nouns) 23

action.......................................................................................................................................................................... 24
GET action ........................................................................................................................................................... 24
alarms ......................................................................................................................................................................... 26
POST alarms (GET Tunneling) .............................................................................................................................. 26
GET alarms .......................................................................................................................................................... 27
PUT alarms .......................................................................................................................................................... 28
DELETE alarms ..................................................................................................................................................... 29
associations ................................................................................................................................................................ 30
POST associations................................................................................................................................................ 30
GET associations .................................................................................................................................................. 31
DELETE associations ............................................................................................................................................ 32
attribute ..................................................................................................................................................................... 33
GET attribute ....................................................................................................................................................... 33

Contents 5
connectivity ................................................................................................................................................................ 34
GET connectivity ................................................................................................................................................. 34
devices ........................................................................................................................................................................ 36
GET devices ......................................................................................................................................................... 36
landscapes .................................................................................................................................................................. 38
GET landscapes ................................................................................................................................................... 38
model ......................................................................................................................................................................... 39
POST model ......................................................................................................................................................... 39
GET model ........................................................................................................................................................... 40
PUT model ........................................................................................................................................................... 42
DELETE model ..................................................................................................................................................... 42
Example: Create a Model Based on Model Type ................................................................................................ 43
models ........................................................................................................................................................................ 44
POST models (GET Tunneling) ............................................................................................................................. 44
GET models ......................................................................................................................................................... 46
PUT models ......................................................................................................................................................... 48
events ......................................................................................................................................................................... 48
POST event .......................................................................................................................................................... 49
POST events ........................................................................................................................................................ 50
subscription ................................................................................................................................................................ 52
POST subscription ............................................................................................................................................... 52
GET subscription ................................................................................................................................................. 56
GET subscription/requests .................................................................................................................................. 56
DELETE subscription ............................................................................................................................................ 57

Chapter 5: Examples 59
Java Code Examples ................................................................................................................................................... 59
Program Arguments ............................................................................................................................................ 60
XML Examples ............................................................................................................................................................ 61
Simple URL Request in Browser ................................................................................................................................. 62
Simple URL Request with Parameters in a Browser ................................................................................................... 63
Using Throttle and Next ............................................................................................................................................. 64
Using URL and GET Tunneling for Same Request ....................................................................................................... 65
URL Request ........................................................................................................................................................ 66
GET Tunneling Request ....................................................................................................................................... 66

Appendix A: Attributes 69

Appendix B: Troubleshooting 71
Common Issues .......................................................................................................................................................... 71

6 Web Services API Reference Guide

"Next" Link Does not Work ........................................................................................................................................ 71

Index 73

Contents 7
Chapter 1: Introduction
This section contains the following topics:
About the CA Spectrum Web Services API (see page 9)
REST Architecture (see page 10)
Supported Technologies (see page 10)
CA Spectrum Web Services API and OneClick (see page 11)
Performance Considerations (see page 12)
Limitations (see page 12)

About the CA Spectrum Web Services API

The CA Spectrum Web Services API provides a RESTful HTTP Web Service interface in CA
Spectrum. This distributed API provides an HTTP-based integration point to the CA
Spectrum data model, allowing web-centric read/write access to devices, models,
relationships, attributes, actions and alarms. The CA Spectrum Web Services API is a
core CA Spectrum component and is installed along with the core CA Spectrum product.

Using the CA Spectrum Web Services API, CA Spectrum data can be accessed directly
from a browser or integrated into your own application. Because of the inherent
standards in the REST architecture, the CA Spectrum Web Services API makes the CA
Spectrum data model accessible to many different external development environments
and methods. The CA Spectrum Web Services API can be used with any language that
knows how to manage HTTP integration and provides a lightweight alternative to SOAP
services.

By using the CA Spectrum Web Services API, you can take advantage of functionality
provided by the OneClick server, such as using its search infrastructure to more easily
find groups of models. You can also perform many standard CA Spectrum functions for a
single SpectroSERVER or in a distributed SpectroSERVER (DSS) environment, such as the
following:
■ Access devices, models, relationships, attributes, actions and alarms
■ Manage devices, ports, containers, services, and links
■ Read, update, and clear alarms
■ Manage subscriptions and notifications

Chapter 1: Introduction 9
REST Architecture

You can use the CA Spectrum Web Services API to perform these functions and more,
similar to those provided by other CA Spectrum API tools such as the Command Line
Interface (CLI), Modeling Gateway, AlarmNotifier, Southbound Gateway, or the
SpectroSERVER Object Request Broker (SSORB) interface.

Note: The CA Spectrum Web Services API can be used for simple CLI ad hoc commands
and as an alternative to complex CLI scripting.

Important! The CA Spectrum Web Services API is a powerful tool. It does not provide
the safeguards that OneClick does, especially related to modeling. It should be used only
by CA Spectrum administrators who understand the potentially harmful effects on a
network modeling scheme of haphazardly creating and destroying models and
modifying model attributes.

REST Architecture
Representational State Transfer (REST) is a software architectural style that promotes
standardized behaviors between interacting elements, or clients and servers.
Conforming to the REST constraints is referred to as being RESTful.

The REST architecture is a lightweight HTTP/HTTPS-based approach for SOAPless Web

Services using create (POST), read (GET), update (PUT), and delete (DELETE) operations,
or verbs.

RESTful architecture and applications are stateless, which means that no client context
information is stored between requests. Each request contains all the information
necessary to service the request.

The CA Spectrum Web Services API supports the REST architecture.

Supported Technologies
The CA Spectrum Web Services API provides a flexible, lightweight RESTful approach for
integration of CA Spectrum data into your application. As an alternative to CORBA
integration, the CA Spectrum Web Services API is language-independent and can be
integrated into any development platform that supports HTTP integration, such as:
■ Java
■ Perl
■ Ruby on Rails
■ .net

The CA Spectrum Web Services API provides an HTTP/HTTPS interface, is both HTTP and
XML/JSON-based, and provides Java Beans for client development.

10 Web Services API Reference Guide

 CA Spectrum Web Services API and OneClick

CA Spectrum Web Services API and OneClick

The CA Spectrum Web Services API is hosted by and sits on top of the OneClick server.
As shown in the following diagram, the CA Spectrum Web Services API servlets provide
the entry point to the OneClick server:

This approach allows full access to OneClick server functions, essentially using the same
code as the OneClick server. You can take advantage of OneClick features such as user
authentication, search capability, and defined alarm filters. Throttled reads provide bulk
query efficiency, and load-balanced OneClick servers provide high availability. The CA
Spectrum Web Services API is fully supported in a distributed SpectroSERVER
environment.

As with all RESTful services, the CA Spectrum Web Services API requests are stateless,
requiring each request to include all necessary information to perform the operation.

Chapter 1: Introduction 11
Performance Considerations

Performance Considerations
The CA Spectrum Web Services API is a client, very similar to OneClick. Because the CA
Spectrum Web Services API reuses much of the OneClick server code, performance of a
single API client should generally mimic the performance of the comparable OneClick
operation. The CA Spectrum Web Services API should not alter SpectroSERVER
performance except through normal request load.

Important! The following can cause performance issues:

– Because data is cached in the OneClick server, large data requests across
multiple clients can cause performance degradation.
– Users can create new, poorly performing searches and execute them through
the CA Spectrum Web Services API, resulting in performance degradation.

Limitations
The following should be considered when using the CA Spectrum Web Services API:
■ The CA Spectrum Web Services API does not provide interfaces for the modeling
catalog where data is generally static.
■ While an HTML or browser application can be built on top of the CA Spectrum Web
Services API, the CA Spectrum Web Services API itself does not provide HTML.
■ The CA Spectrum Web Services API accepts XML only for input and produces XML or
JSON for output. If you choose JSON as output, you may need to parse it out and
produce XML for the next request.

12 Web Services API Reference Guide

Chapter 2: Working with the CA Spectrum
Web Services API
This section contains the following topics:
How to Use the CA Spectrum Web Services API (see page 13)
Requests (see page 13)
Responses (see page 16)
Web Application Description Language (WADL) URL (see page 18)
CA Spectrum Web Services API Files (see page 18)
XML Schema Definitions (see page 18)

How to Use the CA Spectrum Web Services API

The following describes how to use the CA Spectrum Web Services API:
1. Generate a request (see page 13) to the OneClick server. The request can be in the
form of a URL or imbedded in XML content.
The OneClick server processes the request and returns a response.
2. Review the response (see page 16), which contains the results of the request in the
form of an XML or JSON document, depending on the client configuration.
3. Using information returned by the response, such as throttled results or other
request-specific information, you can create follow-up requests.

Both requests and responses are regulated by defined schemas (see page 18).

Requests
To use the CA Spectrum Web Services API, you generate a request to the OneClick
server for which you receive results in response. The request can be in the form of a URL
or imbedded in XML content.

Chapter 2: Working with the CA Spectrum Web Services API 13

Requests

RESTful Web Service URLs are noun-oriented, and the HTTP operation itself represents
the verb. The following is the base URL when generating a request using the CA
Spectrum Web Services API:

http://<hostname><:portnumber>/spectrum/restful/<request>

request
Specifies the CA Spectrum Web Services API RESTful resource (see page 23). Any
request that requires a body will use the types defined in the Request.xsd (see
page 18).
Note: Because RESTful architecture and applications are stateless, no client context
is stored between requests. Each request contains all the information necessary to
service the request in the URL or XML content.

Request Types
There are two types of requests used in the CA Spectrum Web Services API. Both
request types offer the same performance.
URL Requests
Used when a resource targets a specific model. For example, DELETE <mh> deletes
a specific model. This type of request works well for simple requests with few
parameters, does not require body text, and can be used as a browser URL.
Note: All URL requests have GET Tunneling equivalents.
GET Tunneling Requests
Used when a resource targets multiple models using complex parameters. An HTTP
GET command can only support a limited number of parameters in a URL and does
not support a body. The GET Tunneling operation tunnels a GET request through a
POST body, allowing complex requests to be created. The XML body can contain
rich filters by using new and existing search criteria and pre-defined alarm filters.
Semantics of GET Tunneling requests are defined by Request.xsd and Filter.xsd
schemas (see page 18) and can be created manually or generated from request
beans.

14 Web Services API Reference Guide

 Requests

General URL Parameters

The following are general parameters that are supported for some of the resources,
depending on application. In general, the order of URL parameters in a list does not
matter. Any exceptions are noted.

Important! Parameters are preceded by either ? or &. In accordance with standard

HTTP syntax, the first parameter specified must be preceded by ?, and any subsequent
parameters must be preceded by &. All of the following parameters are shown
preceded by &. Use the appropriate prefix depending on the location of the parameter
in the list.
&attr=<attr_ID>&val=<num>
Specifies attribute value pairs, which are used to obtain specific attribute values for
the resource being queried. For example, if you GET alarms, you get the alarm IDs
only by default. However, if you retrieve alarms with specified attributes you get
the alarm IDs with their specific attribute values.
When attribute value pairs are specified, especially when updating attribute values,
attribute ID and values must occur in sequence for proper binding of the ID and
value, as in the following:
?attr=0x10062&val=text&attr=0x10001&val=12334

This pairing tells the RESTful servlet that an attr ID will be followed by the desired
value for that ID when updating the value of the attribute.
Multiple attribute-value pairs can be specified.
&landscape=<landscape_handle>
Specifies which landscapes to include in query. Multiple landscape parameters can
be specified.
&mh=<model_handle>
Specifies the model handle.
&throttlesize=<num>
Specifies the number of items from the result set to retrieve per response. If the
throttlesize value is less than the total number of items in the result set, the results
contain a "next" link. This link can be used to retrieve more results. See Using
Throttle and Next (see page 64).
Note: Not all resources support the throttlesize parameter.

Security
This section contains the following topics:
■ User Security in OneClick (see page 16)
■ Secure Connections (see page 16)

Chapter 2: Working with the CA Spectrum Web Services API 15

Responses

User Security in OneClick

All requests using the CA Spectrum Web Services API respect CA Spectrum user
model-based security.

Important! The CA Spectrum Web Services API is a powerful tool. It does not provide
the safeguards that OneClick does, especially related to modeling. It should be used only
by CA Spectrum administrators with strong knowledge of the CA Spectrum data model.

Secure Connections

The CA Spectrum Web Services API supports secure connections to the OneClick server.
To use secure connections, the OneClick server must be configured for Secure Sockets
Layer (SSL).

Note: For information about configuring OneClick for SSL, see the Administrator Guide.

Responses
Responses are in the form of an XML or JSON document, as determined by the client’s
accept header value/MIME type. This flexible output makes the output data easy to
integrate into client development. Responses are defined by Response.xsd schema (see
page 18).

Note: The CA Spectrum Web Services API supports both application/xml and
application/json MIME types in the accept header. If you choose JSON as output, you
may need to parse it out and produce XML for the next request.

The following describes elements of a response output:

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>

<resource-response-list
xmlns="http://www.ca.com/spectrum/restful/schema/response" error="<msg>"
throttle="<num>" total-resource="<num>">
<resource-responses>
...
</resource-responses>
<link rel="next"
href="http://<hostname><:portnumber>/spectrum/restful/alarms?id=<result_set_ID>&s
tart=3&throttlesize=<num>" type="application/xml" />
</resource-response-list>

16 Web Services API Reference Guide

 Responses

error="<msg>"
Indicates the overall success or failure of the operation. If there is a failure,
additional information is provided. "EndOfResults" indicates that all items in the
result set have been returned.
throttle="<num>"
Indicates the number of items returned in this response, as specified by the
throttlesize parameter on the request. If the throttle number is less than the total
results found by the server, a "next" link is provided. If the complete set of data is
returned, there is no "next" link.
total-resource="<num>"
Indicates the total number of items in the result set. Resource varies depending on
the type of request (for example, alarms, landscape, model, models).
link rel="next" href="<URL>"
Note: The "next" link appears only if additional items remain in the result set.
Indicates that additional items remain in the result set and provides the URL to
obtain them according to the throttle value. This link conforms to the HATEOAS
(Hypermedia as the Engine of Application State) constraints and can be used in a
client or a browser to issue the "next" request. By using this link, the full cost of the
original call is avoided. The location is cached on the OneClick server and expires
after ten minutes of inactivity. After expiration, the URL returns the string "The
cursor is no longer valid".
Note: Each RESTful call has its own cache.
The following parameters appear in the generated URL:
id=<result_set_ID>
Specifies the location of the result set on the OneClick server. The data expires
after ten minutes of inactivity.
start=<element_num>
Indicates the start position within the result set.
throttlesize
Indicates the number of items to return in the next response.
Note: The format of the parameters within the generated link may vary depending
on your environment. For example, "&" may be generated as "&amp;" This is due to
differences between XML, HTTP, and JSON formatting standards.

More information:

Using Throttle and Next (see page 64)

Chapter 2: Working with the CA Spectrum Web Services API 17

Web Application Description Language (WADL) URL

Web Application Description Language (WADL) URL

The following is the WADL URL for the CA Spectrum Web Services API:

http://<hostname><:portnumber>/spectrum/restful/services

Note: The WADL is provided for advanced users and describes the simple URLs but does
not describe GET Tunneling. Use the schema files (see page 18) for GET Tunneling.

CA Spectrum Web Services API Files

CA Spectrum Web Services API files are located in <$SPECROOT>/RestfulExamples,
which includes the following folders:
lib
Contains all .jar files necessary for Java client development.
src
Contains the following folders:
test
Contains example Java code that demonstrates basic functionality, JAXB beans,
and hard-coded XML. An Eclipse .project and .classpath are also provided. For
more information about provided examples, see Java Code Examples (see
page 59).
xsd
Contains xsd files. For more information, see XML Schema Definitions (see
page 18).
xml
Contains sample XML for GET Tunneling requests. For more information about
provided examples, see XML Examples (see page 61).
Note: For more about GET Tunneling, see Simple and Complex Requests (see
page 14).

XML Schema Definitions

Input and output data transfer is done in XML, conforming to a strict schema which
enables standard access to data from different applications. The schemas provided in
the CA Spectrum Web Services API define the correct data layout for all valid requests
and responses.

18 Web Services API Reference Guide

 XML Schema Definitions

Used to define the required syntax for GET Tunneling, the schema files are also more
useful than WADL for advanced usage. The schema files are used to generate the JAXB
beans that can be used for java and java script development. These beans are available
in <$SPECROOT>/RestfulExamples/lib/spectrumrest.jar.

CA Spectrum provides the following XML Schema Definitions (.xsd) files, which are
located in <$SPECROOT>/RestfulExamples/src/xsd:
Filter.xsd
Specifies the XML for attribute filters and search criteria.
Note: This is the same XML that is used by the CA Spectrum Locator; however, the
Filter.xsd is only used by the CA Spectrum Web Services API.
Request.xsd
Defines the XML format used in GET Tunneling. All POST body XML must have a tag
like the following:
xsi:schemaLocation="http://www.ca.com/spectrum/restful/schema/request
../../../xsd/Request.xsd">

Response.xsd
Defines the XML or JSON format for all synchronous responses and XML format for
all asynchronous responses.

Chapter 2: Working with the CA Spectrum Web Services API 19

Chapter 3: REST Operations (Verbs)
The following REST verbs are supported in the CA Spectrum Web Services API. All
operations respect standard CA Spectrum user security.
■ POST (Create)
■ GET (Read)
■ PUT (Update)
■ DELETE (Delete)

Note: The HEAD, OPTIONS, and TRACE verbs are not supported in the CA Spectrum Web
Services API.

Chapter 3: REST Operations (Verbs) 21

Chapter 4: RESTful Resources (Nouns)
The CA Spectrum Web Services API provides the URLs for the appropriate RESTful HTTP
operations against the CA Spectrum data model nouns, as displayed in the following
table. All nouns are lowercase.

Resource Description POST GET PUT DELETE

action (see page 24) Used to send actions yes
alarms (see page 26) Read, update, and delete GET yes yes yes
alarms Tunneling
associations (see page 30) Create, read, update, and yes yes yes
delete associations
attribute (see page 33) Reads values for yes
enumerated attribute
values
connectivity (see page 34) Reads connectivity yes
information for a specified
IP address
devices (see page 36) Reads devices and yes
attributes
landscapes (see page 38) Reads landscape yes
information
model (see page 39) Creates, reads, updates yes yes yes yes
attributes and deletes
models
models (see page 44) Reads and writes models GET yes* yes
attributes Tunneling
events (see page 48) Creates one or more events yes
on single or multiple models
subscription (see page 52) Creates request for change yes yes yes
notification

* GET can only be performed against the result set created by POST (GET Tunneling).

Chapter 4: RESTful Resources (Nouns) 23

action

action
Use the Action resource to issue an action request to the SpectroSERVER. An internal
action code determines which operation is performed by the action.
Base URL
http://<hostname><:portnumber>/spectrum/restful/action

GET action
GET action issues an action request to the SpectroSERVER. Initiated as an HTTP GET, the
action performed on the SpectroSERVER, including modifying data, is specified by an
action code. All actions return results, which differ by the requested action.
URL
http://<hostname><:portnumber>/spectrum/restful/action/<action_code>[?mh=<mod
el_handle>][&attr=<attr_ID>&val=<num>][&throttlesize=<num>]

HTTP Method
GET
Body
None
Body Content
Not used
Header
application/xml, application/json
Output
XML or JSON listing. Content differs depending on requested action.

URL Parameters
action_code
Specifies the action to perform on the SpectroSERVER. The following table contains
some common actions.

Action Target Model Description

0x1000e device Reconfigures a model
(reconfig)
0x480003 watch Activates a watch (activate)

24 Web Services API Reference Guide

 action

Action Target Model Description

0x480004 watch Deactivates a watch
(deactivate)
0x210008 device Reconfigures application
models on Cisco and
Wellfleet devices
(reconfigure_apps)
0x100a2 VNM Updates the SpectroSERVER
with changes to EventDisp
and AlertMap files
(reload_event_disp)
0x100f6 global collection Updates membership for
periodic search-based global
collections
0x10274 VNM Turns on EMS debugging
0x10275 VNM Turns off EMS debugging
0x10301 VNM or global collection Turns on Search Debug for all
searches if directed to the
VNM model or for a single
global collection if directed
to a global collection
0x10300 VNM or global collection Turns off Search Debug for
all searches if directed to the
VNM model or for a single
global collection if directed
to a global collection
0xbc614d RFC2790App Toggles debug for File
System Monitoring
0xbd6146 RFC2790App Toggles debug for Process
Monitoring

&mh=<model_handle>
(Optional) Specifies the target of the action.
&attr=<attr_ID>&val=<num>
(Optional) Specifies attribute values as input to the action. Multiple attribute-value
pairs can be specified.
&throttlesize=<num>
(Optional) Specifies a throttle size.

Chapter 4: RESTful Resources (Nouns) 25

alarms

Example

The following URL initiates the ‘FIND_DEV_MODELS_BY_IP’ action (0x10093) against the
SearchManager model (0x400018):
http://<hostname><:portnumber>/spectrum/restful/action/0x10093?mh=0x400018&attr=0
&val=172.22.96.11&attr=1&val=172.22.96.5

Notes:
■ The SearchManager model handle will differ from SpectroSERVER to
SpectroSERVER.
■ You can also find device models by IP by embedding the correct locater search in
the POST body of a GET models (see page 44).

alarms
Use the Alarms resource to read, modify, and delete CA Spectrum alarms. Asynchronous
responses are supported.
Base URL
http://<hostname><:portnumber>/spectrum/restful/alarms

POST alarms (GET Tunneling)

Use POST alarms (GET Tunneling) to get all alarm IDs. POSTing an alarms request allows
you to provide an XML document that specifies the alarms to be retrieved. The
document can specify specific alarms by ID or by a model specification. A model
specification can be a list of model handles, XML search criteria or a reference to
existing search criteria on the OneClick server. It is also possible to GET alarms that
satisfy a specific alarm attribute filter. An attribute filter is a subset of the search
criteria.

Important! This POST is a form of GET Tunneling. You cannot create an alarm with POST
alarms. CA Spectrum alarms are created in response to events, as defined by the Event
Disposition files.
URL
http://<hostname><:portnumber>/spectrum/restful/alarms

HTTP Method
POST

26 Web Services API Reference Guide

 alarms

Body
Examples are provided in <$SPECROOT>/RestfulExamples/xml/Alarms. These XML
files provide examples of properly formed XML for different purposes. Use these
examples as a basis for your own XML:
■ GetAlarmsByModelHandles.xml
■ GetAlarmsBySearchCriteria.xml
■ GetAlarmsForAllDevices.xml
■ GetAlarmsByAlarmIDs.xml
■ GetAlarmsByAttributeFilter.xml
Body Content
application/xml
Header
application/xml, application/json
Output
XML or JSON listing all alarms in the SpectroSERVER or distributed SpectroSERVER

Example

The following is an example call:

Java GenericPoster noun=Alarms file=resources/xml/Alarms/GetAlarmsBySearch.xml

server=localhost username=jdoe password=spectrum port=8080

GET alarms
GET alarms returns alarm IDs. You can retrieve specific alarm attributes by using the
&attr=<attr_id> parameter.
URL
http://<hostname><:portnumber>/spectrum/restful/alarms[?attr=<attr_ID>][&land
scape=<landscape_handle>][&throttlesize=<num>]

HTTP Method
GET
Body
None
Body Content
Not used

Chapter 4: RESTful Resources (Nouns) 27

alarms

Header
application/xml, application/json
Output
XML or JSON listing alarms in the SpectroSERVER or distributed SpectroSERVER

URL Parameters
&attr=<attr_ID>
(Optional) Specifies the requested attributes. Multiple attribute parameters can be
specified.
Note: There are many attributes on a model; for best performance you should limit
attribute selection to attributes of interest (see page 69).
&landscape=<landscape_handle>
(Optional) Filters which landscapes are queried. Multiple landscape parameters can
be specified.
&throttlesize=<num>
(Optional) Specifies a throttle size.

PUT alarms
Use PUT alarms to update alarm attributes.
URL
http://<hostname><:portnumber>/spectrum/restful/alarms/<alarm_id>?attr=<attr_
ID>&val=<num>

HTTP Method
PUT
Body
None
Body Content
Not Used
Header
application/xml, application/json
Output
XML or JSON listing indicating success or failure

28 Web Services API Reference Guide

 alarms

URL Parameters
alarm_ID
Specifies the alarm ID.
&attr=<attr_ID>&val=<num>
Specifies the attributes and values. Multiple attribute-value pairs can be specified.

DELETE alarms
To delete an alarm using DELETE alarms, include the alarm ID without any other
parameters.
URL
http://<hostname><:portnumber>/spectrum/restful/alarms/<alarm_id>

HTTP Method
DELETE
Body
None
Body Content
Not Used
Header
application/xml, application/json
Output
XML or JSON listing indicating success or failure

URL Parameters
alarm_ID
Specifies the alarm to delete.

Chapter 4: RESTful Resources (Nouns) 29

associations

associations
Use the Associations/Relation resource to create, read, or delete associations.

Note: Associations cannot be updated. To modify an association, delete the existing

association and create a new one. Association operations are restricted to one
SpectroSERVER at a time.
Base URL
http://<hostname><:portnumber>/spectrum/restful/associations/relation

Note: The Associations noun is a pass-through noun. You must also specify the
Relation noun to create, read, or delete associations.

POST associations
POST associations creates an association. A specific relation is created between two
models. Only models on the same SpectroSERVER can be associated.
URL
http://<hostname><:portnumber>/spectrum/restful/associations/relation/<rel_ha
ndle>/leftmodel/<LMhandle>/rightmodel/<RMhandle>

HTTP Method
POST
Body
None
Body Content
Not Used
Header
application/xml, application/json
Output
XML or JSON listing association information

30 Web Services API Reference Guide

 associations

URL Parameters
rel_handle
Specifies the relation handle.
LMhandle
Specifies the handle of the left model in the relation.
RMhandle
Specifies the handle of the right model in the relation.

Note: To get the left or right model handle, you can use the CLI show associations
command, as follows:

show associations mh=<model_handle_of_device/port>

For more information about this command, see the Command Line Interface User Guide.

GET associations
GET associations returns associations for a specific relation and model. Associations are
read based on the side of the association that the model handle is on.
URL
http://<hostname><:portnumber>/spectrum/restful/associations/relation/<rel_ha
ndle>/model/<model_handle>?side=[left|right]

HTTP Method
GET
Body
None
Body Content
Not Used
Header
application/xml, application/json
Output
XML or JSON listing association information

Chapter 4: RESTful Resources (Nouns) 31

associations

URL Parameters
rel_handle
Specifies the relation handle.
model_handle
Specifies the handle of the model in the relation.
side=[left|right]
Specifies the side of the association that the model handle is on.

DELETE associations
DELETE associations removes associations by deleting a specific relation between two
models.
URL
http://<hostname><:portnumber>/spectrum/restful/associations/relation/<rel_ha
ndle>/leftmodel/<LMhandle>/rightmodel/<RMhandle>

HTTP Method
DELETE
Body
None
Body Content
Not Used
Header
application/xml, application/json
Output
XML or JSON listing indicating success or failure

URL Parameters
rel_handle
Specifies the relation handle.
LMhandle
Specifies the handle of the left model in the relation.
RMhandle
Specifies the handle of the right model in the relation.

32 Web Services API Reference Guide

 attribute

attribute
Use the Attribute resource to retrieve strings for enumerated attributes.
Base URL
http://<hostname><:portnumber>/spectrum/restful/attribute

GET attribute
GET attribute returns XML describing the enumerations for the specified attribute.
URL
http://<hostname><:portnumber>/spectrum/restful/attribute/<attr_ID>/enums

HTTP Method
GET
Body
None
Body Content
application/xml, application
Header
application/xml, application/json
Output
XML describing the enumerations for the specified attribute

URL Parameters
attr_ID
Specifies the attribute ID.
Note: Do not use external attributes.

Chapter 4: RESTful Resources (Nouns) 33

connectivity

Example

The following URL requests the enumerations for the model class attribute (0x11ee8):

http://localhost:8080/spectrum/restful/attribute/0x11ee8/enums

The following is returned for the request:

<?xml version="1.0" encoding="UTF-8"?>

<attrtibute-enum-response
xmlns="http://www.ca.com/spectrum/restful/schema/response">
<attribute id="0x11ee8"/>
<enum id="0" value="Unknown"/>
<enum id="1" value="Other"/>
<enum id="2" value="Switch"/>
<enum id="3" value="Router"/>
. . .

connectivity
Use the Connectivity resource to retrieve connectivity information for a specified device
model's IP address.
Base URL
http://<hostname><:portnumber>/spectrum/restful/connectivity

GET connectivity
GET connectivity returns XML describing all the connectivity from a requested end
point.
URL
http://<hostname><:portnumber>/spectrum/restful/connectivity/<ip_address>

HTTP Method
GET
Body
None
Body Content
application/xml, application

34 Web Services API Reference Guide

 connectivity

Header
application/xml, application/json
Output
XML describing the connectivity

URL Parameters
ip_address
Specifies the IP address to retrieve connectivity information for.

Example

The following URL requests connectivity information for the specified IP address:

http://localhost:8080/spectrum/restful/connectivity/172.22.94.134

The following is returned for the request:

?xml version="1.0" encoding="UTF-8"?>

<connection-response-list
xmlns="http://www.ca.com/spectrum/restful/schema/response">
<connection-response>
<connection-element-left>
<ipaddress>172.22.94.134</ipaddress>
<mh>0x400538</mh>
<name>Stack</name>
<type>ExtrDevice</type>
<class>Switch-Router</class>
</connection-element-left>
<connection-element-left>
<ipaddress>172.22.94.134</ipaddress>
<mh>0x400c52</mh>
<name>Stack_1:1</name>
<type>ExtrIfPort</type>
<class>Port</class>
</connection-element-left>
<connection-element-right>
<ipaddress>172.22.94.25</ipaddress>
<mh>0x400449</mh>
<name>cis7204-96.6.ca.com.6.ca.com</name>
<type>Rtr_Cisco</type>
<class>Switch-Router</class>
</connection-element-right>

Chapter 4: RESTful Resources (Nouns) 35

devices

<connection-element-right>
<ipaddress>172.22.94.25</ipaddress>
<mh>0x4007bb</mh>
<name>cis7204-96.6.ca.com.6.ca.com_Fa4/0</name>
<type>Gen_IF_Port</type>
<class>Port</class>
</connection-element-right>
</connection-response>
<connection-response>
<connection-element-left>
<ipaddress>172.22.94.134</ipaddress>

devices
Use the Devices resource to retrieve CA Spectrum devices and attribute information.

Note: A device is defined as all models returned by the SpectroSERVER action

FIND_ALL_DEVICE_MODELS (0x1023a).
Base URL
http://<hostname><:portnumber>/spectrum/restful/devices

GET devices
GET devices returns all device model handles. You can retrieve specific model attributes
by using the &attr=<attr_id> parameter.
URL
http://<hostname><:portnumber>/spectrum/restful/devices[?attr=<attr_ID>][&lan
dscape=<landscape_handle>][&throttlesize=<num>]

HTTP Method
GET
Body
None
Body Content
Not Used
Header
application/xml, application/json
Output
XML or JSON listing all device model handles and requested attributes in the
SpectroSERVER or distributed SpectroSERVER

36 Web Services API Reference Guide

 devices

URL Parameters
&attr=<attr_ID>
(Optional) Specifies the requested attributes. Multiple attribute parameters can be
specified.
Note: There are many attributes on a model; for best performance you should limit
attribute selection to attributes of interest (see page 69).
&landscape=<landscape_handle>
(Optional) Filters which landscapes are queried. Multiple landscape parameters can
be specified.
&throttlesize=<num>
(Optional) Specifies a throttle size.

Example

The following URL requests the name and model type of all devices:

http://<hostname><:portnumber>/spectrum/restful/devices?attr=0x1006e&attr=0x10000

The following is returned for the request:

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>

- <model-response-list xmlns="http://www.ca.com/spectrum/restful/schema/response"
error="EndOfResults" throttle="5" total-models="5">
- <model-responses>
- <model mh="0x1800178">
<attribute id="0x1006e">ciscoRPM-9.18.ca.com</attribute>
<attribute id="0x10000">Rtr_Cisco</attribute>
</model>
- <model mh="0x1800351">
<attribute id="0x1006e">Rtr7301IPT_248</attribute>
<attribute id="0x10000">Rtr_Cisco</attribute>
</model>
- <model mh="0x1800082">
<attribute id="0x1006e">jun2300-96.17</attribute>
<attribute id="0x10000">JuniperJUNOSRtr</attribute>
</model>
- <model mh="0x1800062">
<attribute id="0x1006e">junM7i-96.20</attribute>
<attribute id="0x10000">JuniperJUNOSRtr</attribute>
</model>
- <model mh="0x18002fb">
<attribute id="0x1006e">AdminActive</attribute>
<attribute id="0x10000">HPBladeOnboardAdmin</attribute>
</model>
</model-responses>
</model-response-list>

Chapter 4: RESTful Resources (Nouns) 37

landscapes

landscapes
Use the Landscapes resource to retrieve landscape information.
Base URL
http://<hostname><:portnumber>/spectrum/restful/landscapes

GET landscapes
GET landscapes returns information about all landscapes.
URL
http://<hostname><:portnumber>/spectrum/restful/landscapes
HTTP Method
GET
Body
None
Body Content
Not Used
Header
application/xml, application/json
Output
XML or JSON listing all landscapes in SpectroSERVER or distributed SpectroSERVER

Example

The following URL requests all landscapes:

http://localhost/spectrum/restful/landscapes

The following is returned for the request:

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>

- <landscape-response xmlns="http://www.ca.com/spectrum/restful/schema/response"
total-landscapes="1">
- <landscape>
<id>0x1800000</id>
<name>comp001</name>
<isPrimary>true</isPrimary>
<spectrumVersion>9.2.1.005</spectrumVersion>
</landscape>
</landscape-response>

38 Web Services API Reference Guide

 model

model
Use the model resource to create or delete a model and to read or modify model
attributes. An example that illustrates model creation is included in this section. For
more information, see Example: Create a Model Based on Model Type (see page 43).

Note: The model resource operates on a single model at a time. For groups of models,
use the models (see page 44) resource.
Base URL
http://<hostname><:portnumber>/spectrum/restful/model

POST model
POST model creates a new model and returns the model handle.
URL
http://<hostname><:portnumber>/spectrum/restful/model[?landscapeid=<landscape
_handle>][&mtypeid=<mtype_handle>][&port=<snmp_port>][&commstring=<comm_str>]
[&retry=<retry_cnt>][&timeout=<timeout_val>][&ipaddress=<ip_address>][&parent
mh=<model_handle>][&relationid=<rel_handle>][&attr=<attr_id>&val=<num>]

HTTP Method
POST
Body
None
Body Content
Not Used
Header
application/xml, application/json
Output
XML or JSON listing the model handle of the created model or the error if the model
cannot be created

URL Parameters
&landscapeid=<landscape_handle>
(Optional) Specifies the landscape where the model will be created.
&mtypeid=<mtype_handle>
(Optional) Specifies the model type handle of the model to be created. Required if
the ipaddress parameter is not specified (see below).

Chapter 4: RESTful Resources (Nouns) 39

model

&port=<snmp_port>
(Optional) Specifies the SNMP management port on the device.
Default: 161
&commstring=<comm_str>
(Optional) Specifies the community string.
Default: public
&retry=<retry_cnt>
(Optional) Specifies the retry count.
Default: 3
&timeout=<timeout_val>
(Optional) Specifies the timeout value.
Default: 3000
&ipaddress=<ip_address>
(Optional) Specifies the IP address.
&parentmh=<model_handle>
(Optional) Specifies the parent (left Association) model.
&relationid=<rel_handle>
(Optional) Specifies the association from the parent to this model.
Default: Collects
&attr=<attr_id>&val=<num>
(Optional) Specifies and attribute ID and value.

GET model
GET model reads attributes from the specified model.
URL
http://<hostname><:portnumber>/spectrum/restful/model/<model_handle>[?attr=<a
ttr_ID>]

HTTP Method
GET

40 Web Services API Reference Guide

 model

Body
None
Body Content
Not Used
Header
application/xml, application/json
Output
XML or JSON listing of the requested attributes

URL Parameters
model_handle
Specifies the model.
&attr=<attr_ID>
(Optional) Specifies the requested attributes. Multiple attribute parameters can be
specified.

Chapter 4: RESTful Resources (Nouns) 41

model

PUT model
PUT model updates attributes on the specified model.
URL
http://<hostname><:portnumber>/spectrum/restful/model/<model_handle>?attr=<at
tr_ID>&val=<num>

HTTP Method
PUT
Body
None
Body Content
Not Used
Header
application/xml, application/json
Output
XML or JSON listing of the requested attributes

URL Parameters
model_handle
Specifies the model to update.
&attr=<attr_ID>&val=<num>
Specifies the attributes and values to update. Multiple attribute-value pairs can be
specified.

DELETE model
DELETE model deletes the specified model.
URL
http://<hostname><:portnumber>/spectrum/restful/model/<model_handle>

HTTP Method
DELETE
Body
None
Body Content
Not Used

42 Web Services API Reference Guide

 model

Header
application/xml, application/json
Output
XML or JSON listing indicating success or failure

URL Parameters
model_handle
Specifies the model to delete.

Example: Create a Model Based on Model Type

You can use the POST method to create a model based on a model type. Use the model
noun and the model type ID for the model type that you want to create. You can deploy
this basic method to create pingable models, user models, maintenance schedules,
containers, and any other type of model that you can create using CA Spectrum web
services.

The basic format to use is shown in the following URL. Variables are indicated with
italics:

http://hostname:portnumber/spectrum/restful/model[?mtypeid=
modeltype_of_a_device][&parentmh=model_handle][&relationid=rel_handle][&attr=
attr_id&val=<num>]

Example

Use any REST client to post the following URL:

http://host IP address:portnumber/spectrum/restful/model
?mtypeid=0x00010290&parentmh=0x40000005&attr=0x12d7f&val=10.13.12.111

In this example, we supplied the following parameters:

val
The IP address of a pingable device (in this example, 10.13.12.111).
mtypeid
The model type of a device that you are modeling. In this example, it is a pingable
device, 0x00010290. To find the model type ID for the model type that you want to
create, use the Search feature in the Model Type Editor.
parentmh
The model_handle for a universe.

Chapter 4: RESTful Resources (Nouns) 43

models

relationid
(Optional) The relation ID to identify an association between two models in the
model domain (a relation).
attr
The attribute ID of ipaddress. The value is the device IP address.

models
Use the Models resource to retrieve and update models and attributes.

Note: The models resource operates on groups of models. For a single model, use the
model (see page 39) resource.
Base URL
http://<hostname><:portnumber>/spectrum/restful/models

POST models (GET Tunneling)

Use POST models to get all model handles and requested attributes. POSTing a models
request lets you provide an XML document that specifies the models to retrieve. The
document contains a list of model handles, XML search criteria, or a reference to
existing search criteria on the OneClick server.

Important! POST models is a form of GET Tunneling used to retrieve multiple models.
You cannot create a model with POST models. To create a model, use POST model (see
page 39).
URL
http://<hostname><:portnumber>/spectrum/restful/models

HTTP Method
POST

44 Web Services API Reference Guide

 models

Body
Examples are provided in <$SPECROOT>/RestfulExamples/xml/Models. These XML
files provide examples of properly formed XML for different purposes. Use these
examples as a basis for your own XML:
■ GetCiscoRouterModels.xml
■ GetModelsByModelHandles.xml
■ GetModelsFromExistingSearch.xml
Body Content
application/xml
Header
application/xml, application/json
Output
XML or JSON listing of models satisfying the request input in the SpectroSERVER or
distributed SpectroSERVER

Example: Java CALL

The following is an example call:

Java GenericPoster noun=Models file=resources/xml/Models/GetCiscoRouterModels.xml

server=localhost username=jdoe password=spectrum port=8080

Example: Request XML to find device models by IP address

The following is an example of how to find device models by IP address by embedding

the correct locater search in the POST body of a models GET. This operation searches all
landscapes in a distributed SpectroSERVER environment as well as allowing you to
specify the attributes of interest.

URL

POST the following XML body to:

http://<hostname><:portnumber>/spectrum/restful/models

Chapter 4: RESTful Resources (Nouns) 45

models

Body

<?xml version="1.0" encoding="UTF-8"?>

<rs:model-request throttlesize="5"
xmlns:rs="http://www.ca.com/spectrum/restful/schema/request"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.ca.com/spectrum/restful/schema/request
../../../xsd/Request.xsd ">

<rs:target-models>
<rs:models-search>
<rs:search-criteria
xmlns="http://www.ca.com/spectrum/restful/schema/filter">
<action-models>
<filtered-models>
<equals>
<model-type>SearchManager</model-type>
</equals>
</filtered-models>
<action>FIND_DEV_MODELS_BY_IP</action>
<attribute id="AttributeID.NETWORK_ADDRESS">
<value>172.22.96.6</value>
</attribute>
</action-models>
</rs:search-criteria>
</rs:models-search>
</rs:target-models>

<rs:requested-attribute id="0x1006e" />

<rs:requested-attribute id="0x10000" />
<rs:requested-attribute id="0x10032" />
<rs:requested-attribute id="0x12de2" />

</rs:model-request>

GET models
GET models returns model handles and requested attributes. To retrieve specific model
attributes, use the &attr=<attr_id> parameter.

Important! GET models can be used only after a POST (GET Tunneling) models has been
performed. POST models generates the result set, and GET models is used to retrieve
model handles and attribute information for the items within that result set.

46 Web Services API Reference Guide

 models

URL
http://<hostname><:portnumber>/spectrum/restful/models?id=<result_set_pointer
>[&attr=<attr_ID>][&landscape=<landscape_handle>][&throttlesize=<num>]

HTTP Method
GET
Body
None
Body Content
Not used
Header
application/xml, application/json
Output
XML or JSON listing of models satisfying the request input in the SpectroSERVER or
distributed SpectroSERVER

URL Parameters
?id=<result_set_pointer>
Specifies the location of the result set on the OneClick server. This value is
generated by using POST (GET Tunneling) models (see page 44) and appears on the
"next" relative link (see page 16). The location expires on the OneClick server after
ten minutes of inactivity.
&attr=<attr_ID>
(Optional) Specifies the requested attributes. Multiple attribute parameters can be
specified.
Note: There are many attributes on a model; for best performance you should limit
attribute selection to attributes of interest (see page 69). Not all models support
the same set of attributes. Unsupported attributes will return ‘NoSuchAttribute’
&landscape=<landscape_handle>
(Optional) Filters which landscapes are queried. Multiple landscape parameters can
be specified.
&throttlesize=<num>
(Optional) Specifies a throttle size.

Chapter 4: RESTful Resources (Nouns) 47

events

PUT models
PUT models updates attributes across multiple models. The models can be selected by a
variety of techniques including search criteria. Not all selected models need to support
the attributes being modified.
URL
http://<hostname><:portnumber>/spectrum/restful/models

HTTP Method
PUT
Body
Uses Request.xsd:update-models-request. The Request.xsd is located in
<$SPECROOT>/RestfulExamples/src/xsd
Body Content
application/xml, application
Header
application/xml, application/json
Output
XML or JSON listing of model-response indicating the success or failure of each
update.

events
Use the events resource to create events.

Note: The events resource operates on a single model or groups of models.

Base URL
http://<hostname><:portnumber>/spectrum/restful/events

48 Web Services API Reference Guide

 events

POST event
POST event creates a new event.
URL
http://<hostname><:portnumber>/spectrum/restful/events/<eventType>/model/<mod
el handle>[?varbind=<varbind id>][&val=<varbind value>]

HTTP Method
POST
Body
None
Body Content
Not Used
Header
application/xml, application/json
Encoding
UTF-8
Output
XML or JSON listing the model handle of the created model or the error if the model
cannot be created.

URL Parameters
<event type>
Specifies the event type to be created.
<model handle>
Specifies the model handle on which the event will be created.
<varbind id>
Specifies the varbind id.
<varbind value>
Specifies the varbind value.

Chapter 4: RESTful Resources (Nouns) 49

events

POST events
Use POST events to create one or more events on one or more models. POSTing an
events request lets you provide an XML document that specifies the events to create
and the models on which to create them. The document contains a list of model
handles, XML search criteria, or a reference to existing search criteria on the OneClick
server.
URL
http://<hostname><:portnumber>/spectrum/restful/events

HTTP Method
POST
Body
Examples are provided in <$SPECROOT>/RestfulExamples/xml/Events. These XML
files provide examples of properly formed XML for different purposes. Use these
examples as a basis for your own XML:
■ CreateEventByModelHandleList.xml
■ CreateEventByModelSearch.xml
■ CreateMultipleEventsByModelHandle.xml
Body Content
application/xml
Header
application/xml, application/json
Encoding
UTF-8
Output
XML or JSON listing of models satisfying the request input in the SpectroSERVER or
distributed SpectroSERVER

Example: Create an event 0x10f06 on all RTR_Cisco Model Types, with 4 varbinds

The following is an example of creating an event 0x10f06 on all RTR_Cisco Model Types,
with 4 varbinds
URL

Post the following XML body to:

http://<hostname><:portnumber>/spectrum/restful/events

Body

<?xml version="1.0" encoding="UTF-8"?>

50 Web Services API Reference Guide

 events

<!--This sample event request will create an event of type 0x10f06 (generates a High
Memory Utilization alarm) on all models found by the specified locater search (all
models derived from RTR_Cisco) -->

<rs:event-request throttlesize="10"
xmlns:rs="http://www.ca.com/spectrum/restful/schema/request"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.ca.com/spectrum/restful/schema/request
../../../xsd/Request.xsd">

<rs:event>

<rs:target-models>

<rs:models-search>

<rs:search-criteria

xmlns="http://www.ca.com/spectrum/restful/schema/filter">

<filtered-models>

<is-derived-from>

<attribute id="AttributeID.MTYPE_HANDLE">

<value>0x21000c</value> <!-- RTR_Cisco -->

</attribute>

</is-derived-from>

</filtered-models>

</rs:search-criteria>

</rs:models-search>

</rs:target-models>

<!-- event ID -->

<rs:event-type id="0x10f06"/>

<!-- attributes/varbinds -->

<rs:varbind id="0">75</rs:varbind>

<rs:varbind id="1">99</rs:varbind>

<rs:varbind id="3">mem_instance</rs:varbind>

Chapter 4: RESTful Resources (Nouns) 51

subscription

<rs:varbind id="5">name</rs:varbind>

</rs:event>

</rs:event-request>

subscription
Use the Subscription resource to create or retrieve subscriptions. A subscription is a
request to be notified of activity on any of the following:
■ Model types/attributes. Registers watches for model creation/deletion of type and
attribute changes on those types.
Note: ModelType subscriptions watch for new models.
■ Models/attributes. Registers watches on specified models and related attribute
changes.
■ Alarms/attributes. Registers watches for alarm creation/clearing and attribute
changes.
Base URL
http://<hostname><:portnumber>/spectrum/restful/subscription

POST subscription
POST subscription creates a new subscription. Subscriptions are pull or push. A pull
subscription requires that the client poll the subscription ID whereas a push subscription
requires that the client provide a URL to which notifications can be POSTed.
Notifications contain change information in XML or JSON format.

Note: Push subscriptions are useful when the integration client is another OneClick
server.
URL
http://<hostname><:portnumber>/spectrum/restful/subscription

HTTP Method
POST

52 Web Services API Reference Guide

 subscription

Body
Uses Request.xsd:subscription-request. The Request.xsd is located in
<$SPECROOT>/RestfulExamples/src/xsd
For specific examples of Subscription XML, see the following:
■ In <$SPECROOT>/RestfulExamples/xml/Alarms:
■ PullAlarmsSubscription.xml
■ In <$SPECROOT>/RestfulExamples/xml/Models
■ PullAttrWatchForAllDevices.xml
■ In <$SPECROOT>/RestfulExamples/xml/MTypes:
■ PullWatchForNewMTypes.xml
■ PushWatchForNewMTypes.xml
■ PushWatchForNewMTypesBatchMode.xml
■ PushWatchForNewMTypesNoExpiration.xml
Body Content
application/xml, application
Header
application/xml, application/json
Output
XML or JSON listing the subscription-id
subscription-id
Identifies the subscription. This value is used with GET subscription (see
page 56) and DELETE subscription (see page 57) and expires if not used.

Chapter 4: RESTful Resources (Nouns) 53

subscription

Body Parameters

The following parameters are used in the subscription request body XML.
■ For pull subscriptions:
max-notifications
Specifies the number of notification items.
Default: 100
max-queue-size
Specifies the number of notifications to queue.
Default: 10000
pull-interval
Specifies the frequency of polling in milliseconds.
Note: Subscriptions expire if not polled.
Minimum: 5000
■ For push subscriptions:
destination-url
Specifies the URL where notifications will be POSTed.
A test notification servlet has been provided that prints results to the CA
Spectrum tomcat log. This servlet is installed with CA Spectrum, and no
additional configuration is required. To use the servlet, set the destination-url
to:
http://<hostname><:portnumber>/spectrum/restful/TestNotifications

Each time a notification is received it is printed to the CA Spectrum tomcat log,

as follows:
■ For Windows: <$SPECROOT>/tomcat/logs
■ For Solaris and Linux: <$SPECROOT>/tomcat/logs/catalina.out
username
Specifies the user name required by the destination URL.
password
Specifies the password required by the destination URL.

54 Web Services API Reference Guide

 subscription

batch-notifications
max-notifications
Specifies the number of notifications in a batch. If this number is reached,
notification is sent immediately.
Default: 100
max-time
Specifies the time in milliseconds to wait before sending notifications. If
this number is reached, notifications are sent immediately.
Default: 1000
heartbeat-interval
Specifies the interval in milliseconds that the subscription is validated. The
subscription servlet sends a message every hearbeat-interval to the receiving
servlet (designated by the destination-url) to indicate that the subscription is
active. If the receiving servlet stops receiving the heartbeat message, it knows
that the subscription has stopped (for example, if the OneClick server stops or
restarts). If the receiving servlet becomes unavailable, notifications stop.
Note: The TestNotifications servlet does not print the heartbeat message.

Example

The following is an example subscription registration snippet:

<rs:destination-url>http://<hostname><:portnumber>/spectrum/restful/TestNotificat
ions</rs:destination-url>
<rs:username><user></rs:username>
<rs:password><password></rs:password>

The following is an example Java call:

Java GenericPoster noun=Models file=

RestfulExamples/xml/Models/PullAttrWatchForAllDevices.xml server=localhost
username=jdoe password=spectrum port=8080

Chapter 4: RESTful Resources (Nouns) 55

subscription

GET subscription
Use GET subscription to return XML describing all the changes of interest based on the
initial subscription request.

Note: GET subscription applies to the pull model only.

URL
http://<hostnumber><:portnumber>/spectrum/restful/subscription/<subscription_
ID>

HTTP Method
GET
Body
None
Body Content
application/xml, application
Header
application/xml, application/json

URL Parameters
subscription_ID
Specifies the subscription ID. This value is returned from the original subscription
request (POST subscription (see page 52)) or GET subscription/requests (see
page 56). It is used to obtain the set of changes since the last request.

GET subscription/requests
Use GET subscription/requests to return a string of the current, active subscriptions.
This request is used primarily for debugging or verification purposes to see if a particular
model, type or attribute is registered for notification.

Note: To pull the actual model, model type, and attribute changes, see GET subscription
(see page 56).

56 Web Services API Reference Guide

 subscription

URL
http://<hostname><:portnumber>/spectrum/restful/subscription/requests

HTTP Method
GET
Body
None
Body Content
application/xml, application
Header
application/xml, application/json
Output
HTML page listing the subscription-id and other subscription-related information for
each current, active subscription
subscription-id
Identifies a subscription. This value is used with GET subscription (see page 56)
and DELETE subscription (see page 57).

DELETE subscription
DELETE subscription deletes the specified subscription.
URL
http://<hostname><:portnumber>/spectrum/restful/subscription/<subscription_ID
>

HTTP Method
DELETE

Chapter 4: RESTful Resources (Nouns) 57

subscription

Body
None
Body Content
application/xml, application
Header
application/xml, application/json

URL Parameters
subscription_ID
Specifies the subscription to delete. This value is returned from the original
subscription request (POST subscription (see page 52)) or GET subscription/requests
(see page 56).

58 Web Services API Reference Guide

Chapter 5: Examples
This section contains the following topics:
Java Code Examples (see page 59)
XML Examples (see page 61)
Simple URL Request in Browser (see page 62)
Simple URL Request with Parameters in a Browser (see page 63)
Using Throttle and Next (see page 64)
Using URL and GET Tunneling for Same Request (see page 65)

Java Code Examples

The CA Spectrum Web Services API provides example Java code that demonstrates basic
functionality, JAXB beans, and hard-coded XML. An Eclipse .project and .classpath are
also provided. The files are located in <$SPECROOT>/RestfulExamples/src/test.

Note: Each of the example programs requires certain parameter values to be provided.
See Program Arguments (see page 60).

The following examples are provided in the /client subfolder.

AlarmPoller
Subscribe for and pull alarms.
CreateSimilarModels
Create many models of the same type.
GenericPoster
A generic way to POST XML.
GetAllAlarms
A simple alarm reader.
GetAllDevices
A simple example that reads attributes on devices.
GetAllLandscapes
The simplest example.
GlobalCollectionExample
Creates a new Global Collection Model.

For more information, see the readme.txt files and internal documentation.

Chapter 5: Examples 59
Java Code Examples

Program Arguments
The following program arguments are used by the provided Java code examples.
server={server}
Specifies the host name of the OneClick server.
username={username}
Specifies a user name for the OneClick server.
password={password}
Specifies the username password for the OneClick server.
method={method}
Specifies the REST verb, or HTTP method.
Values: GET, POST, PUT, DELETE
port={port}
(Optional) Specifies the port number of the OneClick server.
Default: 80
accept={acceptType}
(Optional) Specifies the accept header value/MIME type.
Values: application/xml, application/json
Default: application/xml
inputdata={inputdataType}
(Optional) Specifies the body content type.
Value: application/xml

60 Web Services API Reference Guide

 XML Examples

secure=true|false
(Optional) Specifies whether to secure the connection to the OneClick server.
Default: False
If set to True, the following parameters are required:
keystore_file={fqfn for keystore file}
Specifies the fully-qualified keystore file name.
keystore_password={keystore password}
Specifies the password for the keystore.
alias={certificate alias}
Specifies the certificate alias name.
Note: To use a secure connection, the OneClick server must be configured for SSL.
For information about configuring OneClick for SSL, see the Administrator Guide.

XML Examples
The CA Spectrum Web Services API provides example XML for GET Tunneling requests.
The files are located in <$SPECROOT>/RestfulExamples/xml.

The following examples are provided:

Alarms
■ GetAlarmsByAlarmIDs.xml
■ GetAlarmsByAttributeFilter.xml
■ GetAlarmsByModelHandles.xml
■ GetAlarmsBySearchCriteria.xml
■ GetAlarmsForAllDevices.xml
■ PullAlarmsSubscription.xml
Events
■ CreateEventByModelHandleList.xml
■ CreateEventByModelSearch.xml
■ CreateMultipleEventsByModelHandle.xml

Chapter 5: Examples 61
Simple URL Request in Browser

Models
■ GetCiscoRouterModels.xml
■ GetModelsByModelHandles.xml
■ GetModelsFromExistingSearch.xml
■ PullAttrWatchForAllDevices.xml
■ PutModelsByModelHandles.xml
ModelTypes (MTypes)
■ PullWatchForNewMTypes.xml
■ PushWatchForNewMTypes.xml
■ PushWatchForNewMTypesBatchMode.xml
■ PushWatchForNewMTypesNoExpiration.xml

Simple URL Request in Browser

This example shows a GET landscapes request and results in a browser window. The GET
verb is implied in the browser environment. Parameters are not necessary on the URL to
return a list of all landscapes in the distributed SpectroSERVER environment.

62 Web Services API Reference Guide

 Simple URL Request with Parameters in a Browser

Simple URL Request with Parameters in a Browser

This example uses the devices noun with URL parameters to request the name
(0x1006e) and model type (0x10000) of all devices. The GET verb is implied in the
browser environment.

Chapter 5: Examples 63
Using Throttle and Next

Using Throttle and Next

This example uses GET alarms to retrieve all alarms and shows how the throttle and
"next" link are used.

Follow these steps:

1. Use the following request, which asks for all alarms to be returned but only three at
a time:
http://comp001/spectrum/restful/alarms?throttlesize=3

Notice the following in this request:

throttlesize
Indicates the number of items to return at a time. This example requests three
alarms to be returned at a time.
The following response returns from the SpectroSERVER. This response indicates
that a total of five alarms exist and only three are returned. A relative link is
provided that points to the next items in the list.
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
- <alarm-response-list
xmlns="http://www.ca.com/spectrum/restful/schema/response" throttle="3"
total-alarms="5">
- <alarm-responses>
<alarm id="4e77f4fd-1c9b-1000-0336-000874f00c29" />
<alarm id="4e77f4fe-1ca2-1000-0336-000874f00c29" />
<alarm id="4e80da2b-a48e-1001-0336-000874f00c29" />
</alarm-responses>
<link rel="next"
href="http://comp001/spectrum/restful/alarms?id=c6a367df-0b3e-4461-aa8d-
aad451a45bf7&start=3&throttlesize=3" type="application/xml" />
</alarm-response-list>

Notice the following in this response:

throttle
Indicates the number of items returned in this response. In this example, three
alarms have been returned in this response.
total-alarms
Indicates the total number of items in the result set. In this example, there a
five total alarms in the result set.

64 Web Services API Reference Guide

 Using URL and GET Tunneling for Same Request

link rel="next"
Indicates the URL to retrieve the next items in the result set. This link can be
used in a browser or a program to issue the next request.
id=<result_set_ID>
Specifies the location of the result set on the OneClick server. The data
expires after ten minutes of inactivity.
start=<element_num>
Indicates the position within the result set.
2. Use the "next" relative link from the previous response to request the next three
items in the result set:
http://comp001/spectrum/restful/alarms?id=c6a367df-0b3e-4461-aa8d-
aad451a45bf7&start=3&throttlesize=3

The following response returns from the SpectroSERVER:

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
- <alarm-response-list
xmlns="http://www.ca.com/spectrum/restful/schema/response"
error="EndOfResults" throttle="2" total-alarms="5">
- <alarm-responses>
<alarm id="4e83d694-18e1-1002-0336-000874f00c29" />
<alarm id="4e77f4fe-1c9e-1000-0336-000874f00c29" />
</alarm-responses>
</alarm-response-list>

Notice the following in this response:

error="EndOfResults"
Indicates that all items in the list have been retrieved.

Using URL and GET Tunneling for Same Request

This example shows the same request made by a URL request and a GET Tunneling
request.
■ URL Request (see page 66)
■ GET Tunneling Request (see page 66)

Chapter 5: Examples 65
Using URL and GET Tunneling for Same Request

URL Request
This examples uses GET devices, in a simple URL request format, to retrieve attributes
for all devices, throttling at 100.

Initial request

This request specifies the attributes to read:

http://localhost/spectrum/restful/devices?attr=0x1006e&attr=0x10000&attr=0x10032&
attr=0x12de2&throttlesize=100

All matching devices are found and cached. The first 100 devices are returned, and, if
there are more than 100, a link to get the next 100.

Subsequent request

Using the link from the initial request response, the following request pulls the next set
of results from the cache:

http://localhost/spectrum/restful/devices?id=0120a63a-e2d3-4175-9563-c17c90c783a7
&start=100&throttlesize=100

GET Tunneling Request

This examples uses GET devices, in imbedded XML request format, to retrieve attributes
for all devices, throttling at 100.

66 Web Services API Reference Guide

 Using URL and GET Tunneling for Same Request

The following portions of Request.xsd are of interest for this example. This request uses
the model-request type. The type definition determines the parameters that can be
specified, in this case, "target-models", "requested-attribute", and "throttlesize".

Note: See the complete contents in

<$SPECROOT>/RestfulExamples/src/xsd/Request.xsd.

<xs:complexType name="model-request">
<xs:sequence>
<xs:element name="target-models" type="rs:target-models" minOccurs="1"
maxOccurs="1" />
<xs:element name="requested-attribute" type="rs:requested-attribute"
minOccurs="0" maxOccurs="unbounded" />
</xs:sequence>
<xs:attribute name="throttlesize" type="xs:int" />
</xs:complexType>
.
.
.

<xs:complexType name="target-models">
<xs:choice>
<xs:element name="model" type="rs:model" minOccurs="0" maxOccurs="unbounded" />
<xs:element name="models-search" type="rs:models-search" minOccurs="0"
maxOccurs="1"/>
</xs:choice>
</xs:complexType>
.
.
.
<!-- Elements -->

<xs:element name="alarm-request" type="rs:alarm-request" />

<xs:element name="model-request" type="rs:model-request" />
<xs:element name="subscription-request" type="rs:subscription-request" />
<xs:element name="update-models-request" type="rs:update-models-request" />

Chapter 5: Examples 67
Appendix A: Attributes
The follow table contains alarm and model attributes that are commonly used when
using the CA Spectrum Web Services API. Italicized items are model attributes that
might be of interest for alarms. Non-italicized items are alarm-specific attributes.

Attribute Specification Attribute Name Data Type

0x10000 Model Type Name Text String
0x10001 Model Type of Alarmed Model Type Handle
Model
0x10009 Security String Text String
0x1000a Condition Integer
0x1006e Model Name Text String
0x11ee8 Model Class Integer
0x11f4d Acknowledged Boolean
0x11f4e Creation Date Date
0x11f4f Alarm Status Text String
0x11f50 Cause Code Integer
0x11f52 Event ID List Octet String
0x11f53 Model Handle of Alarmed Model Handle
Model
0x11f54 Primary Alarm Boolean
0x11f56 Severity Integer
0x11f57 Troubleshooter Text String
0x11f9b User Clearable Boolean
0x11f9c Alarm ID Octet String
0x11fc4 Alarm Source Enumeration (0=Current,
1=Residual)
0x11fc5 Occurrences Gauge
0x11fc6 Troubleshooter Model Model Handle
Handle
0x12022 Trouble Ticket ID Text String
0x1296e Originating Event Octet String

Appendix A: Attributes 69
Using URL and GET Tunneling for Same Request

Attribute Specification Attribute Name Data Type

0x12a04 Symptom List Octet String
0x12a05 Cause List Octet String
0x12a06 Symptom Count Integer
0x12a07 Cause Count Integer
0x12a56 Significant Model ID Integer
0x12a63 Web Context URL Text String
0x12a6f Event Symptom List Octet String
0x12a70 Event Symptom Count Integer
0x12a82 IP to Domain Map Octet String
0x12b4c Alarm Title Text String
0x12c05 Secure Domain Display Text String
0x12d7f Network Address Internet Address
0x12d83 Secure Domain Address Internet Address

70 Web Services API Reference Guide

Appendix B: Troubleshooting
This section contains the following topics:
Common Issues (see page 71)
"Next" Link Does not Work (see page 71)

Common Issues
If you are experiencing problems when using the CA Spectrum Web Services API, check
the following:
■ Is the URL constructed correctly?
■ Is the correct verb used with the noun?
■ Is the Request XML for GET Tunneling constructed correctly?
■ Have the proper credentials been entered?
■ Has the "accept" header and "Content-type" been set correctly for XML or JSON?
■ Do any CA Spectrum Web Services API errors appear in the tomcat log?

More information:

XML Schema Definitions (see page 18)

Java Code Examples (see page 59)
XML Examples (see page 61)

"Next" Link Does not Work

Symptom:
The "next" link that was generated in a response does not work correctly when I try to
retrieve the next throttled set of results.

Appendix B: Troubleshooting 71
"Next" Link Does not Work

Solution:
The format of the parameters within the generated link may vary depending on your
environment. For example, "&" may be generated as "&amp;" This is due to differences
between XML, HTTP, and JSON formatting standards. Notice the difference in the
prefixes for the start and throttlesize parameters in the following URLs:

http://localhost/spectrum/restful/models?id=5b03b5ba-64ed-4603-b3e1-8e71919fccd8&
amp;start=2&amp;throttlesize=2

http://localhost/spectrum/restful/models?id=5b03b5ba-64ed-4603-b3e1-8e71919fccd8&
start=2&throttlesize=2

To correct, change '&amp' to '&' in your URL.

Note: This applies to XML only (not JSON).

72 Web Services API Reference Guide

Index
C
contacting technical support • 3
customer support, contacting • 3

S
support, contacting • 3

T
technical support, contacting • 3

Index 73