|
Table Of Contents
Cisco CRS-1 Series XML API Overview
Cisco CRS-1 Series Management XML Interface
Cisco CRS-1 Series XML API and Cisco CRS-1 Series Router System Features
Cisco CRS-1 Series XML API Tags
Cisco CRS-1 Series XML API Overview
This chapter contains the following sections:
• Cisco CRS-1 Series Management XML Interface
• Cisco CRS-1 Series XML API and Cisco CRS-1 Series Router System Features
• Cisco CRS-1 Series XML API Tags
Introduction
The Cisco CRS-1 Series Carrier Routing System XML API Guide explains how to use the Cisco CRS-1 Series XML API to configure Cisco CRS-1 Series routers or request information about configuration, management, or operation of Cisco CRS-1 Series routers. The goal of this guide is to help Cisco CRS-1 Series router customers write client applications to interact with the Cisco CRS-1 Series XML infrastructure on the router, and to also use the Cisco CRS-1 Series Management XML API to build custom end-user interfaces for configuration and information retrieval and display.
The extensible markup language (XML) application programming interface (API) provided by the Cisco CRS-1 Series Carrier Routing System (Cisco CRS-1 Series) is an interface used for rapid development of client applications and perl scripts to manage and monitor the Cisco CRS-1 Series router. The XML interface is specified by the Cisco CRS-1 Series XML schemas. The XML API provides a mechanism for router configuration and monitoring utilizing an exchange of XML formatted request and response streams.
Client applications can be used to configure the router, or to request status information from the router, by encoding a request in Cisco CRS-1 Series XML API tags and sending it to the router. The Cisco CRS-1 Series router processes the request and sends the response to the client by again encoding the response in Cisco CRS-1 Series XML API tags. This guide describes the XML requests that can be sent by external client applications to access router management data, and also details the responses to the client by the Cisco CRS-1 Series router.
The Cisco CRS-1 Series XML API readily supports available transport layers. The initial release of the API supports the Common Object Request Broker Architecture (CORBA). Later on, the API can support additional transport options.
Customers use a variety of vendor-specific command line interface (CLI) scripts to manage their routers because no alternative programmatic mechanism is available. In addition, a common framework has not been available to develop CLI scripts. In response to this need, Cisco CRS-1 Series XML API provides the necessary common framework for rapid development, deployment, and maintenance of
Cisco CRS-1 Series router management.
Note The XML API code is available for use on any Cisco platform that runs Cisco IOS XR software.
Definition of Terms
Table 1-1 defines the words, acronyms, and actions used throughout this guide.
Cisco CRS-1 Series Management XML Interface
This guide provides the following information regarding the Cisco CRS-1 Series management XML interface:
•High-level structure of the Cisco CRS-1 Series XML request and response streams
•Operation tag types and usage, including their XML format and content
•How to use Cisco CRS-1 Series XML to configure the Cisco CRS-1 Series router:
–Using the two-stage "target configuration" mechanism provided by the Cisco CRS-1 Series configuration manager
–Using features such as locking, loading, browsing, modifying, saving, and committing the configuration
•Accessing the Cisco CRS-1 Series router's operational data with XML
•Working with the native management data object class hierarchies:
–To represent the native data objects in XML
–To use various techniques for structuring XML requests to access the management data of interest, including the use of wildcards and filters
•Encapsulating CLI commands in XML
•How error information is returned to the client application
•Using iterators for large data retrieval
•Handling event notifications with XML
•How authorization of client requests is enforced
•Versioning of the Cisco CRS-1 Series XML schemas
•Generation and packaging of the Cisco CRS-1 Series XML schemas
Cisco CRS-1 Series XML API and Cisco CRS-1 Series Router System Features
Using the Cisco CRS-1 Series XML API, an external client application can send XML encoded management requests to an XML agent running on the Cisco CRS-1 Series router. The initial release of the API supports CORBA as the transport mechanism. Using CORBA, the client application sends XML encoded requests to the router through remote operation calls. The remote operation interface is implemented on the router by the CORBA specific XML agent. Later on, the Cisco CRS-1 Series XML API can support other transport mechanisms, which might include terminal based protocols such as Telnet and Secure Shell (SSH). The Cisco CRS-1 Series XML API interface described in this document applies equally to all supported transports.
Before an XML session is established, the XML transport and XML agent must be enabled on the router. For more information, see Chapter 11, "XML Transport and Event Notifications."
A client request sent to the Cisco CRS-1 Series router must specify the different types of operations to be carried out. The following three general types of management operations are supported through XML:
•Native data access (get, set, delete, and so on) using the native management data model.
•Configuration services for more advanced configuration management through the Configuration Manager.
•Traditional CLI access where the CLI commands and command responses are encapsulated in XML.
When a client request is received by an XML agent on the router, the request is routed to the appropriate XML operation provider in the internal Cisco CRS-1 Series XML API library for processing. After all the requested operations are processed, the XML agent receives the result and then sends the XML encoded response stream on to the client.
Figure 1-1 presents a high level view of the XML manageability-related components along with the request and response flows between the client application and the Cisco CRS-1 Series router.
Figure 1-1 XML Components and Request/Response Flows
Cisco CRS-1 Series XML API Tags
An external client application can access management data on the Cisco CRS-1 Series router through an exchange of well structured XML-tagged request and response streams. The XML taggest request and response streams are described in the following sections:
Basic XML Request Content
This section describes the specific content and format of the XML data exchanged between the client and the Cisco CRS-1 Series router for the purpose of router configuration and monitoring.
Top-Level Structure
The top level of every request sent by a client application to the Cisco CRS-1 Series router must begin with an XML declaration tag followed by a request tag and one or more operation type tags. Similarly, every response returned by the Cisco CRS-1 Series router must begin with an XML declaration tag followed by a response tag and one or more operation type tags. Each request can contain operation tags for each supported operation type and the operation type tags can be repeated. The operation type tags contained in the response corresponds to those contained in the client request.
Sample XML Request from Client Application
<?xml version="1.0" encoding="UTF-8"?>
<Request MajorVersion="1" MinorVersion="0">
<Operation>
.
.
.
Operation-specific content goes here
.
.
.
</Operation>
</Request>
Sample XML Response from Router
<?xml version="1.0" encoding="UTF-8"?>
<Response MajorVersion="1" MinorVersion="0">
<Operation>
.
.
.
Operation response data returned here
.
.
.
</Operation>
</Response>
Note All examples in this document are formatted with new lines and white space to aid readability. Actual XML request and response streams exchanged with the Cisco CRS-1 Series router do not include new lines and white space characters because these elements would add significantly to the size of the XML data and impact the overall performance of the Cisco CRS-1 Series XML API.
XML Declaration Tag
Each request and response exchanged between a client application and the Cisco CRS-1 Series router must begin with an XML declaration tag indicating which version of XML and (optionally) which character set are being used:
<?xml version="1.0" encoding="UTF-8"?>
Table 1-2 defines the attributes of the XML declaration that are defined by the XML specification.
Request and Response Tags
Following the XML declaration tag a client application must enclose each request stream within a set of <Request> start and </Request> end tags. Also, the Cisco CRS-1 Series system encloses each XML response within a set of <Response> start and </Response> end tags. A major and minor version number are carried on the <Request> and <Response> elements to indicate the overall
Cisco CRS-1 Series XML API version in use by the client application and router respectively.The Cisco CRS-1 Series XML API presents a synchronous interface to client applications. The <Request> and <Response> tags are used by the client to correlate the request and response streams. A client application can issue a request after which the Cisco CRS-1 Series router returns a response. The client can then issue another request, and so on. Therefore, the XML session between a client and the Cisco CRS-1 Series router consist of a series of alternating requests and response streams.
The client application optionally includes a ClientID attribute within the <Request> tag. The value of the ClientID attribute must be an unsigned 32-bit integer value. If the <Request> tag contains a ClientID attribute, the Cisco CRS-1 Series router includes the same ClientID value in the corresponding <Response> tag. The ClientID value is treated as opaque data and is ignored by the router.
Maximum Request Size
The maximum size of an XML request or response is determined by the restrictions of the underlying transports.
Note For more information on transport specific limitations of request and response sizes, see Chapter 11, "XML Transport and Event Notifications."
Minimum Response Content
If a <Get> request has nothing to return for a particular operation, the Cisco CRS-1 Series router returns the original request and an appropriate empty operation type tag. The minimum response returned by the Cisco CRS-1 Series router in the case of a single operation (for example, <Get>, <Set>, <Delete>) with no result data is shown in the following example.
Sample XML Request from Client Application
<?xml version="1.0" encoding="UTF-8"?>
<Request MajorVersion="1" MinorVersion="0">
<Operation>
.
.
.
Operation-specific content goes here
.
.
.
</Operation>
</Request>
Sample XML Minimum Response from Cisco CRS-1 Series Router
<?xml version="1.0" encoding="UTF-8"?>
<Response MajorVersion="1" MinorVersion="0">
<Operation/>
</Response>
Operation Type Tags
Following the <Request> tag, the client application must specify the operation types to be carried out by the Cisco CRS-1 Series router. There are three general types of operations supported along with the <GetNext> operation for large responses. Each of these operation types is described in the following sections.
Native Data Operation Tags
Native data operations provide basic access to the Cisco CRS-1 Series native management data model. Table 1-3 describes the native data operation tags.
Tip The XML schema definitions for the native data operation type tags are contained in the schema file common_types.xsd.
The native data operations are described further in Chapter 5, "Cisco CRS-1 Series XML and Native Data Access Techniques."
Configuration Services Operation Tags
Configuration services operations provide more advanced configuration management functions through the Cisco CRS-1 Series Configuration Manager. Table 1-4 describes the configuration services operation tags.
Note The XML schema definitions for the configuration services operation type tags are contained in the schema file cfgmgr_operations.xsd (see Chapter 13, "Cisco CRS-1 Series XML Schemas").
Note The configuration services operations are described further in Chapter 2, "Cisco CRS-1 Series XML Router Configuration and Management."
CLI Operation Tag
CLI access provides support for XML encapsulated CLI commands and responses. For CLI access, a single tag is provided. The <CLI> operation tag issues the request as a CLI command.
Note The XML schema definitions for the CLI tag are contained in the schema file common_types.xsd (see Chapter 13, "Cisco CRS-1 Series XML Schemas").
Note The CLI operations are described further in Chapter 6, "Cisco CRS-1 Series XML and Encapsulated CLI Operations."
GetNext Operation Tag
The <GetNext> tag is used to retrieve the next portion of a large response. It can be used as required to retrieve an oversize response following a request using one of the other operation types. The<GetNext> operation tag gets the next portion of a response. Iterators are supported for large requests.
Note The XML schema definition for the <GetNext> operation type tag is contained in the schema file common_types.xsd (see Chapter 13, "Cisco CRS-1 Series XML Schemas").
Note The get next operation is described further in Chapter 7, "Cisco CRS-1 Series XML and Large Data Retrieval (Iterators)."
XML Request Batching
The Cisco CRS-1 Series XML interface supports the combining of several requests or operations into a single request. When multiple operations are specified in a single request, the response contains the same operation tags and in the same order as they appeared in the request.
Batched requests are performed "best effort." For example, if there are operations 1 through 3 in the request and operation 2 fails, operation 3 will be attempted.
Before combining multiple operations inside one <Get> tag, any operations that request multiple items of data must be sent in a separate document. For more information, see Chapter 5, "Cisco CRS-1 Series XML and Native Data Access Techniques," "XML Request with Combined Object Class Hierarchies" section on page 5-67.
The following example shows a simple request containing six different operations:
Sample XML Client Batched Requests
<?xml version="1.0" encoding="UTF-8"?>
<Request MajorVersion="1" MinorVersion="0">
<Lock/>
<Get>
<Configuration>
.
.
.
Get operation content goes here
.
.
.
</Configuration>
</Get>
<Set>
<Configuration>
.
.
.
Set operation content goes here
.
.
.
</Configuration>
</Set>
<Commit/>
<Get>
<Operational>
.
.
.
Get operation content goes here
.
.
.
</Operational>
</Get>
<Unlock/>
</Request>
Sample XML Response from the Cisco CRS-1 Series Router
<?xml version="1.0" encoding="UTF-8"?>
<Response MajorVersion="1" MinorVersion="0">
<Lock/>
<Get>
<Configuration>
.
.
.
.
.
.
.
.
.
Get response content returned here
.
.
.
.
.
.
.
.
.
</Configuration>
</Get>
<Set/>
<Commit/>
<Get>
<Operational>
.
.
.
.
.
.
.
.
.
Get response content returned here
.
.
.
.
.
.
.
.
.
</Operational>
</Get>
<Unlock/>
</Response>
Posted: Sun Nov 7 12:47:49 PST 2004
All contents are Copyright © 1992--2004 Cisco Systems, Inc. All rights reserved.
Important Notices and Privacy Statement.