1. CA Spectrum Web Services API
<script>
CA Spectrum Web Services API
CA Spectrum r9.2.1 Differences

2. Welcome Welcome to the CA Spectrum Web Services API
Spectrum Web Services API will be called SWS in this presentation
Prerequisites:
Required Knowledge:
Knowledge of Spectrum Data Model
HTTP/HTTPS
XML and/or JSON
Schema (XSD)
Helpful Knowledge:
CLI
REST
JAXB
CA Spectrum r9.2.1 Differences

3. Available Resources
Documentation (available on support.ca.com) includes:
Web Services API Reference Guide
CA Spectrum r9.2.1 Differences

4. Course Objectives After completing this course, you will be able to:
Understand the reasons for using the Spectrum Web Services
Understand the RESTful nouns supported by Spectrum
Understand how to make RESTful calls from the browser and from the RESTCLient for testing
Understand how to use GET Tunneling
Understand the contract first design
The role of the Schema files (XSD )
Why you need to know:
To provide support for customers
To develop integrations
To properly QA SWS Changes
This course does NOT teach every use of the API in detail
CA Spectrum r9.2.1 Differences

5. Agenda 1 2 3 4 6 7 Overview What SWS Accomplishes Architecture
<script>
The ordered agenda for this course is as follows… 1
Overview 2
What SWS Accomplishes 3
Architecture 4
Request XSD 6
Troubleshooting 7
Knowledge Check / Session Review
CA Spectrum r9.2.1 Differences

6. What SWS API Accomplishes – Overview
Module Test
<script>
What SWS API Accomplishes – Overview
Course Test

7. Definitions
REST – REpresentation State Transfer A lightweight HTTP/HTTPS based approach for Soapless Web Services using CRUD operations on nouns and verbs
CRUD is an acronym for
Create – HTTP POST
Read – HTTP GET
Update – HTTP PUT
Delete – HTTP DELETE
The RESTful definition specifies that
CRUD operations use application nouns
CRUD operations use HTTP verbs
All operations are stateless

8. Simple Examples
Get all Landscapes
Noun: landscapes
Verb: GET

9. Simple Examples Get Model Name and Model Type Handle for all Devices
Noun: devices
Verb: GET

10. What SWS API Accomplishes – Overview
Provides HTTP/HTTPS interface to Spectrum
Provides new distributed API for external development
Provides an integration point that is similar to, but better than CLI and CORBA
Works in a DSS
Provides throttling
Provides Search Manager Integration
HTTP and XML/JSON based
Provides Java Beans for client development
CA Spectrum r9.2.1 Differences

11. Intended Uses SWS is intended to be used as
Language independent API for integration
Java
Perl
Ruby on Rails
.net
{ more }
Alternative to a CORBA integration
Alternative to Complex CLI scripting
SWS may be used for, but is not really intended to replace
Simple CLI adhoc commands
SWS is not intended to
Provide a browser interface to Spectrum
Produce HTML

12. What gets installed?
Tomcat/common/lib – Jars used by the Servlets in the OCS
spectrumrest.jar
spectrumrestclient.jar
$(SPECROOT)/RestfulExamples (Useful for customers)
lib
All jars necessary for Java client development
src
Java test code
xsd – Schema files
xml
Sample xml for GET Tunneling Requests
E.g. GetCiscoRouterModels.xml, PullAttrWatchForAllDevices.xml, PullAlarmsSubscription.xml

13. Customer facing examples
Java Code examples demonstrate
Basic functionality
JAXB beans
Hardcoded xml
Running the Java Examples
Examples can be loaded an run in Eclipse
An Eclipse .project and .classpath are provided in RestfulExamples/
A README.txt is provided in RestfulExamples/

14. Customer Facing Java Examples
Existing Java Code Examples
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, read attrs on Devices
GetAllLandscapes – The simplest example
GlobalCollectionExample – Creates a new Global Collection Model
Potential for new code examples
Customer feedback and questions may drive new examples

15. Customer Facing XML Examples
Alarms
GetAlarmsByAlarmIDs.xml
GetAlarmsByAttributeFilter.xml
GetAlarmsByModelHandles.xml
GetAlarmsBySearchCriteria.xml
GetAlarmsForAllDevices.xml
PullAlarmsSubscription.xml
Models
GetCiscoRouterModels.xml
GetModelsByModelHandles.xml
GetModelsFromExistingSearch.xml
PullAttrWatchForAllDevices.xml
PutModelsByModelHandles.xml
ModelTypes
PullWatchForNewMTypes.xml
PushWatchForNewMTypes.xml
PushWatchForNewMTypesBatchMode.xml
PushWatchForNewMTypesNoExpiration.xml

16. How SWS API Works – Architecture
Module Test
<script>
How SWS API Works – Architecture
Course Test

17. SWS – Architecture
SWS is a client very similar to OneClick (a GUI less OneClick perhaps?)
SWS is implemented as a Servlet in the OneClick Server
SWS reuses much of the OneClick Server code

18. How Spectrum Web Services API Works – Architecture
Network Configuration Manager
How Spectrum Web Services API Works – Architecture
Talking points:
OneClick talks http/https to the OCS Servlets
The OCS servlets use OCS core code to talk CORBA to the SpectroSERVERs
RESTful http/https calls talk to the SWS servlets
The SWS servlets use OCS core code (possibly including the OCS Servlets) to talk CORBA to the SpectroSERVERs
Since the SWS servlets use the same code as core OCS/OC, the performance and behavior of the SWS should be the same as OC
SWS can manage a DSS whereas CORBA clients and CLI can only talk to one SS at a time
CLI
RESTful HTTP/HTTPS
CORBA Client
OneClick Server (OCS)
SpectroSERVER (SS)
CORBA
http
SWS Servlets
CORBA
SpectroSERVER (SS)
CORBA
http
OneClick
Servlets
Important:
SWS uses the SAME code as the OCS to get data from the SS
SPECTRUM Support Spectacular Training

19. How RESTful Web Services Works – Architecture
Talking Points from Architecture diagram
OneClick talks http/https to the OCS Servlets
The OCS servlets use OCS core code to talk CORBA to the SpectroSERVERs
RESTful http/https calls talk to the SWS servlets
The SWS servlets use OCS core code (possibly including the OCS Servlets) to talk CORBA to the SpectroSERVERs
Since the SWS servlets use the same code as core OCS/OC, the performance and behavior of the SWS should be the same as OC
SWS can manage a DSS whereas CORBA clients and CLI can only talk to one SS at a time

20. Performance Considerations
SWS Clients use 95% existing code in the OneClick Server
Performance of a single SWS Client should generally mimic performance of comparable OC operation
Data is cached in the OneClick Server so large data requests across multiple clients can cause performance issues – SWS or OneClick
Users can create new, poorly performing searches and execute them through SWS
SWS should not alter SpectroSERVER performance except through new searches and normal request load

21. Comparison Highlights of SWS to CLI/CORBA
Shows important comparison notes between solutions
Comparison to CLI
SWS operations are similar to CLI operations
SWS uses throttling, CLI does not (show models |grep myModel) YUCK!
SWS uses search xml to find models of interest, CLI does not
SWS does not provide catalog data other than enums, CLI does (is it really needed?)
SWS uses xml for complex operations (GET Tunneling), CLI does not
Comparison to CORBA
SWS provides asynchronous notification as does CORBA
SWS talks to the DSS, CORBA only talks to one SS at a time
SWS uses OCS core code to unify the data, e.g. GlobalAlarm

22. SWS Nouns Action – Used to send actions
Alarms – Read, Update and Delete Alarms
Associations - Create, Read Update and Delete
Attribute/enums – Reads values for enumerated attribute values
Connectivity – Reads Connectivity information for a specified IP Address
Devices – Reads Devices and attributes
Lansdscapes – Reads Landscape information
Model – Creates, Reads, Updates Attributes and Deletes models
Models – Reads and Writes Models attributes
Subscription – Creates request for change notification
TestNotifications – Test Servlet for subscription notification

23. SWS Response Format
Responses are either XML or JSON – defined by ‘accept’ header
Responses are defined by Response.xsd schema
Must understand how to read a XSD
Beans are created (by JAXB) for all XSD elements; rich programming paradigm
Creation of XML or JSON is done by JAXB so there is no code overhead in Spectrum

24. GET Tunneling GET Tunneling Tunnels a GET request through a POST body
Why? Only POST and PUTs can have a body, GET cannot
Allows creation of complex GET requests
Semantics of GET Tunneling Requests are defined by
Request.xsd – Defines possible XML for GET Tunneling Requests
Filter.xsd – Defines possible XML for search-criteria
Requests are either XML or JSON as defined by ‘Content-Type’
The key to being successful with GET Tunneling is to learn how to read XSD files

25. Subscriptions Subscriptions provide two notification models
Push Style - Changes are delivered to a registered URL
Subscribe with URL and credentials
Change XML/JSON is delivered to the URL
Intended to be used when integration client is another Web Server
Heartbeat can be used to ensure OneClick Server is running
Pull Style - Client must poll to check for changes
Subscribe for changes returns ‘Subscription id’
Client must poll the subscription-id to find changes
Unpolled subscriptions will expire after predefined time

26. Subscriptions Subscriptions can be made for
A ModelType Subscription is usually better than a model subscription, it watches for new models!
Subscriptions can be made for
Model Types / Attributes – Registers watches for model creation/deletion of type and attribute changes on those types
Models / Attributes – Registers watches on specified models and related attribute changes
Alarms / Attributes – Registers watches for alarm creation/clearing and attribute changes.
TestNotifications is an OCS Servlet that can be used for simple testing
Example subscription registration snippet
<rs:destination-url>
<rs:username><user></rs:username>
<rs:password><password></rs:password>
Output is written to the tomcat log
Servlet is intended for use by
Internal users, Dev, QA, Support for validating subscriptions
External Users, Customer testing

27. Understanding URL Requests and Request XSD - Examples

28. URL Requests vs GET Tunneling Requests
URL Requests are for
Simple requests with few parameters
Easier because no Request XML is required
Most URL Requests have a richer, more expressive GET Tunneled form
GET Tunneling Requests
Use Request XML, handcrafted or generated from Request Beans
XML can define a complex request
Harder because they require more knowledge
URL and GET Tunneling Requests offer the same performance
URL and GET Tunneling request are not symmetrical! GET Tunneled requests do NOT have a URL form but any URL form has a GET Tunneled equivalent

29. Example of a URL Request and the same Request using GET Tunneling

30. Examples Simple URL GET attributes for all Devices
Retrieve the model name for all Devices, throttling at 100
No Request XML is used, this is a URL GET
Noun: devices
Verb: GET
Get the first 100
32&attr=0x12de2&throttlesize=100
This returns the first 100 devices and if there are more than 100, a link to get the next 100
Get the next 100 using the returned link
c17c90c783a7&start=100&throttlesize=100
You already understand the next concept – Amazon et al use it to show pages of results! It is built on HATEOAS (Hypermedia as the Engine of Application State)
The first request specifies the attributes to read, all matching devices are found and cached. The second request uses the ‘id’ to pull the next set from the cache
Each RESTful call has its own cache – they are NOT shared

31. Examples Simple XML GET attributes for all Devices
<?xml version="1.0" encoding="UTF-8"?>
<rs:model-request throttlesize="100"
xmlns:rs="
xmlns:xsi="
xsi:schemaLocation=" ../../../xsd/Request.xsd ">
<rs:target-models>
<rs:models-search>
<rs:search-criteria-file>
topo/config/search-devices-criteria.xml
</rs:search-criteria-file>
</rs:models-search>
</rs:target-models>
<rs:requested-attribute id="0x1006e" /> <!-- Model Name -->
<rs:requested-attribute id="0x10000" /> <!-- Model Type Name -->
<rs:requested-attribute id="0x10032" /> <!-- Manufacturer -->
<rs:requested-attribute id="0x12de2" /> <!-- NRM_RunningFirmwareFilters -->
</rs:model-request>
Throttlesize set to 100
Schema is important!
Leverages existing search in OCS
Attributes to read
Remember: This XML could be JSON

32. Now let’s decompose the XSD behind this xml
Advanced Topic
All root types are at the bottom of the Request.xsd
<!-- 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" />
<xs:element name="association-request" type="rs:association-request" />
<?xml version="1.0" encoding="UTF-8"?>
<rs:model-request throttlesize="100"
xmlns:rs="
xmlns:xsi="
xsi:schemaLocation=" ../../../xsd/Request.xsd ">
<rs:target-models>
<rs:models-search>
<rs:search-criteria-file>
topo/config/search-devices-criteria.xml
</rs:search-criteria-file>
</rs:models-search>
</rs:target-models>
<rs:requested-attribute id="0x1006e" /> <!-- Model Name -->
<rs:requested-attribute id="0x10000" /> <!-- Model Type Name -->
<rs:requested-attribute id="0x10032" /> <!-- Manufacturer -->
<rs:requested-attribute id="0x12de2" /> <!-- NRM_RunningFirmwareFilters -->
</rs:model-request>
A model-request is of type model-request, we must examine the model-request type

33. Request Decomposition Example - Continued
Advanced Topic
Schema Definition for model-request
<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>
A model-request has a sequence of
1 and only 1 target-models
0 or more requested-attribute
An optional throttlesize attribute
<?xml version="1.0" encoding="UTF-8"?>
<rs:model-request throttlesize="100"
xmlns:rs="
xmlns:xsi="
xsi:schemaLocation=" ../../../xsd/Request.xsd ">
<rs:target-models>
<rs:models-search>
<rs:search-criteria-file>
topo/config/search-devices-criteria.xml
</rs:search-criteria-file>
</rs:models-search>
</rs:target-models>
<rs:requested-attribute id="0x1006e" /> <!-- Model Name -->
<rs:requested-attribute id="0x10000" /> <!-- Model Type Name -->
<rs:requested-attribute id="0x10032" /> <!-- Manufacturer -->
<rs:requested-attribute id="0x12de2" /> <!-- NRM_RunningFirmwareFilters -->
</rs:model-request>
A sequence means each item is represented, but if minOccurs is 0, the item is optional

34. Request Decomposition Example - Continued
Advanced Topic
Schema Definition for target-models
<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>
A target-models has a choice of
0 or more model
0 or 1 models-search
<?xml version="1.0" encoding="UTF-8"?>
<rs:model-request throttlesize="100"
xmlns:rs="
xmlns:xsi="
xsi:schemaLocation=" ../../../xsd/Request.xsd ">
<rs:target-models>
<rs:models-search>
<rs:search-criteria-file>
topo/config/search-devices-criteria.xml
</rs:search-criteria-file>
</rs:models-search>
</rs:target-models>
<rs:requested-attribute id="0x1006e" /> <!-- Model Name -->
<rs:requested-attribute id="0x10000" /> <!-- Model Type Name -->
<rs:requested-attribute id="0x10032" /> <!-- Manufacturer -->
<rs:requested-attribute id="0x12de2" /> <!-- NRM_RunningFirmwareFilters -->
</rs:model-request>

35. Request Decomposition Example - Continued
Advanced Topic
Schema Definition for models-search
<xs:complexType name="models-search">
<xs:choice>
<xs:element name="search-criteria-file" type="xs:string" />
<xs:element name="search-criteria" type="filter:search-criteria" />
</xs:choice>
</xs:complexType>
A models-search has a choice of
1 search-criteria-file
1 search-criteria
<?xml version="1.0" encoding="UTF-8"?>
<rs:model-request throttlesize="100"
xmlns:rs="
xmlns:xsi="
xsi:schemaLocation=" ../../../xsd/Request.xsd ">
<rs:target-models>
<rs:models-search>
<rs:search-criteria-file>
topo/config/search-devices-criteria.xml
</rs:search-criteria-file>
</rs:models-search>
</rs:target-models>
<rs:requested-attribute id="0x1006e" /> <!-- Model Name -->
<rs:requested-attribute id="0x10000" /> <!-- Model Type Name -->
<rs:requested-attribute id="0x10032" /> <!-- Manufacturer -->
<rs:requested-attribute id="0x12de2" /> <!-- NRM_RunningFirmwareFilters -->
</rs:model-request>

36. Module Test
<script>
Troubleshooting
Course Test

37. Common Mistakes and Causes
General Issues
Most problems arise when
Users construct the wrong URL
Users use the wrong verb with the noun
Users construct invalid Request XML for GET Tunneling
Invalid credentials
Incorrect “accept” or “Content-type”
Refer to the documentation and XSD files
Tail the tomcat log to see if an error is reported from the Servlet
Note: Error messages for mostly correct URLs / XML are often helpful, Error messages for badly formed URLs / XML can be confusing

38. Spectrum OneClick Debugging
Enable on the Spectrum Web Server Debug Page
Output is written to the tomcat log

39. Specific Common Problem
XML Encoding in next link
Problem: Next link returned by throttled results does not work or throttlesize does not work
Solution: XML has encoded the next link, href= 0cab52c472b3&start=5&throttlesize=5, change the & to &
This only applies to XML NOT JSON
This is a common novice problem

40. RESTClient
The RESTClient is a free utility in which you can issue CRUD operations
Download it from:
Download the restclient-ui jar-with-dependencies.jar
The RESTClient is a great way to test URLs and XML Requests / Responses
Since Each REST call is stateless, each URL and Request can be tested by itself
Configuration
Headers Tab, add accept, application/xml or application/json depending on the type you want back
Method Tab, select POST, Body Tab, Edit Content Type, changing it from text/plain to application/xml
Auth Tab, Select Basic and add your Spectrum userid and password
Tools, Options, Etc., Auto-indent Response Body

41. Configuration of RESTClient
Set accept Header to application/xml or application/json
Set Body Content-Type to application/xml or application/json
Set Auth type to Basic and provide Spectrum Credentials

42. Simple GET using RESTClient
Simple get of all devices with model name
XML response, only one device in this DSS

43. I requested JSON in this case
POST of model-request
Uses existing search xml in tomcat\webapps\spectrum\WEB-INF\topo\config
I requested JSON in this case

44. Knowledge Check/Summary
Module Test
<script>
Knowledge Check/Summary
Course Test

45. Review Question Spectrum Web Services API provides
<script>
Spectrum Web Services API provides
HTTP and HTTPS access to Spectrum data
URL and POST data interfaces for retrieving data
Can interface with a DSS thru the OneClick Server
All of the above
CA Spectrum r9.2.1 Differences

46. Review Question Spectrum Web Services API provides
<script>
Spectrum Web Services API provides
HTTP and HTTPS access to Spectrum data
URL and POST data interfaces for retrieving data
Can interface with a DSS thru the OneClick Server
All of the above
CA Spectrum r9.2.1 Differences

47. Course Summary You should now know the following about SWS:
the purpose
the architecture
the basic nouns and verbs
the role of the Response, Request and Filter schema files (xsd)
how GET tunneling messages can be formed from understanding the Request and Filter schema files
differences between SWS, CLI and CORBA
how searches make SWS powerful
how XML and JSON are supported
monitoring the tomcat log for errors
some of the common errors
where the components and examples are located
Why GET Tunneling and Subscriptions make SWS as powerful as CORBA
CA Spectrum r9.2.1 Differences

48. Conclusion Thank you for participating in this Course
<script>
Thank you for participating in this Course
To exit, click the Exit button located at the top right of the screen, or close your browser window
CA Spectrum r9.2.1 Differences