Cisco IOS XR XML API Guide, Cisco IOS XR Release 4.1
Cisco XML API Overview
Downloads: This chapterpdf (PDF - 459.0KB) The complete bookPDF (PDF - 7.34MB) | Feedback

Cisco XML API Overview

Table Of Contents

Cisco XML API Overview

Introduction

Definition of Terms

Cisco Management XML Interface

Cisco XML API and Router System Features

Cisco XML API Tags

Basic XML Request Content

Top-Level Structure

XML Declaration Tag

Request and Response Tags

ResultSummary Tag

Maximum Request Size

Minimum Response Content

Operation Type Tags

Native Data Operation Tags

Configuration Services Operation Tags

CLI Operation Tag

GetNext Operation Tag

Alarm Operation Tags

XML Request Batching


Cisco XML API Overview


This chapter contains these sections:

Introduction

Cisco Management XML Interface

Cisco XML API and Router System Features

Cisco XML API Tags

Introduction

This Cisco IOS XR XML API Guide explains how to use the Cisco XML API to configure routers or request information about configuration, management, or operation of the routers. The goal of this guide is to help management application developers write client applications to interact with the Cisco XML infrastructure on the router, and to use the Management XML API to build custom end-user interfaces for configuration and information retrieval and display.

The XML application programming interface (API) provided by the router is an interface used for development of client applications and perl scripts to manage and monitor the router. The XML interface is specified by XML schemas. The XML API provides a mechanism, which exchanges XML formatted request and response streams, for router configuration and monitoring.

Client applications can be used to configure the router or to request status information from the router, by encoding a request in XML API tags and sending it to the router. The router processes the request and sends the response to the client by again encoding the response in 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 router.

Customers use a variety of vendor-specific 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, the XML API provides the necessary common framework for development, deployment, and maintenance of 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.

Table 1-1 Definition of Terms

Term
Description

AAA

Authentication, authorization, and accounting.

CLI

Command-line interface.

SSH

Secure Shell.

SSL

Secure Sockets Layer.

XML

Extensible markup language.

XML agent

Process on the router that receives XML requests by XML clients, and is responsible to carry out the actions contained in the request and to return an XML response to the client.

XML client

External application that sends XML requests to the router and receives XML responses to those requests.

XML operation

Portion of an XML request that specifies an operation that the XML client wants the XML agent to perform.

XML operation provider

Code that carries out a particular XML operation including parsing the operation XML, performing the operation, and assembling the operation XML response.

XML request

XML document sent to the router containing a number of requested operations to be carried out.

XML response

Response to an XML request.

XML schema

XML document specifying the structure and possible contents of XML elements that can be contained in an XML document.


Cisco Management XML Interface

These topics, which are covered in detail in the sections that follow, outline information about the Cisco Management XML interface:

High-level structure of the XML request and response streams

Operation tag types and usage, including their XML format and content

Configuring the router using:

the two-stage "target configuration" mechanism provided by the configuration manager

features such as locking, loading, browsing, modifying, saving, and committing the configuration

Accessing the operational data of the router with XML

Working with native management data object class hierarchies to:

represent native data objects in XML

use techniques, including the use of wildcards and filters, for structuring XML requests that access the management data of interest,

Encapsulating CLI commands in XML

Error reporting to the client application

Using iterators for large scale data retrieval

Handling event notifications with XML

Enforcing authorization of client requests

Versioning of XML schemas

Generation and packaging of XML schemas

Transporting options that enable corresponding XML agents on the router

Using the Cisco IOS XR Perl Scripting Toolkit to manage a Cisco IOS XR router

Cisco XML API and Router System Features

Using the XML API, an external client application sends XML encoded management requests to an XML agent running on the router. The XML API readily supports available transport layers including terminal-based protocols such as Telnet, Secure Shell (SSH), dedicated-TCP connection, and Secure Sockets Layer (SSL) dedicated TCP connection.

Before an XML session is established, the XML transport and XML agent must be enabled on the router. For more information, see Chapter 13, "XML Transport and Event Notifications."

A client request sent to the router must specify the different types of operations that are to be carried out. Three general types of management operations supported through XML are:

Native data access (get, set, delete, and so on) using the native management data model.

Configuration services for advanced configuration management through the Configuration Manager.

Traditional CLI access where 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 XML API library for processing. After all the requested operations are processed, the XML agent receives the result and sends the XML encoded response stream on to the client.

Cisco XML API Tags

An external client application can access management data on the router through an exchange of well-structured XML-tagged request and response streams. The XML tagged request and response streams are described in these sections:

Basic XML Request Content

XML Declaration Tag

Operation Type Tags

XML Request Batching

Basic XML Request Content

This section describes the specific content and format of XML data exchanged between the client and the 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 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 router begins with an XML declaration tag followed by a response tag, one or more operation type tags, and a result summary tag with an error count. Each request contains operation tags for each supported operation type; these 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-specific response data returned here
     .
     .
     .
</Operation>
<ResultSummary ErrorCount="0"/>
</Response>


Note All examples in this document are formatted with line breaks and white space to aid readability. Actual XML request and response streams that are exchanged with the router do not include such line breaks and white space characters. This is because these elements would add significantly to the size of the XML data and impact the overall performance of the XML API.


XML Declaration Tag

Each request and response exchanged between a client application and the router must begin with an XML declaration tag indicating which version of XML and (optionally) which character set is 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.

Table 1-2 Attributes for XML Declaration 

Name
Description

Version

Specifies the version of XML to be used. Only Version "1.0" is supported by the router.

Note The version attribute is required.

Encoding

Specifies the standardized character set to be used. Only "UTF-8" is supported by the router. The router includes the encoding attribute in a response only if it is specified in the corresponding request.

Note The encoding attribute is optional.


Request and Response Tags

Following the XML declaration tag, the client application must enclose each request stream within a pair of <Request> start and </Request> end tags. Also, the system encloses each XML response within a pair of <Response> start and </Response> end tags. Major and minor version numbers are carried on the <Request> and <Response> elements to indicate the overall XML API version in use by the client application and router respectively.

The XML API presents a synchronous interface to client applications. The <Request> and <Response> tags are used by the client to correlate request and response streams. A client application issues a request after which, the router returns a response. The client then issues another request, and so on. Therefore, the XML session between a client and the 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 router includes the same ClientID value in the corresponding <Response> tag. The ClientID value is treated as opaque data and ignored by the router.

ResultSummary Tag

The system adds a <ResultSummary> tag immediately before the </Response> end tag to indicate the overall result of the operation performed. This tag contains the attribute ErrorCount to indicate the total number of errors encountered. A value of 0 indicates no errors. If applicable, the ItemNotFound or ItemNotFoundBelow attributes are also included. See Table 1-3 for explanations of these attributes.

Sample XML Response with ResultsSummary Tag

<?xml version="1.0" encoding="UTF-8"?>
<Response MajorVersion="1" MinorVersion="0"> 
.
.
<ResultSummary ErrorCount="0" ItemNotFoundBelow="true"/>
</Response>

Maximum Request Size

The maximum size of an XML request or response is determined by the restrictions of the underlying transports. For more information on transport-specific limitations of request and response sizes, see Chapter 13, "XML Transport and Event Notifications."

Minimum Response Content

If a <Set> or <Delete> request has nothing to return, the router returns the original request and an appropriate empty operation type tag. The minimum response returned by the router with a single operation <Set> or <Delete> and no result data, is shown in these examples:

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 a Router

<?xml version="1.0" encoding="UTF-8"?>
<Response MajorVersion="1" MinorVersion="0">
 <Operation/>
<ResultSummary ErrorCount="0"/>
</Response>

If a <Get> request has nothing to return, the router returns the original request with an ItemNotFound attribute at the <Get> level.

If a <Get> request has some `not found' elements to return, the router returns the original request with an ItemNotFoundBelow attribute at the <Get> level. For each requested element that is not found, the router returns a NotFound attribute at the element level. For each requested element that is present, it returns the corresponding data.

Table 1-3 defines the attributes when the <Get> request does not have any elements to return.

Table 1-3 Attributes for Elements Not Found 

Attribute
Description

ItemNotFound

Empty response at the <Get> level.

ItemNotFoundBelow

Response with some requested elements that are not found at the <Get> level.

NotFound

Requested element is not found at the element level.


Sample XML Request from Client Application (ItemNotFound)

<?xml version="1.0"?>
<Request MajorVersion="1" MinorVersion="0">
<Get>
  <Configuration>
    <InterfaceConfigurationTable>
      <InterfaceConfiguration>
        <Naming>
          <Active>act</Active>
          <InterfaceName>Loopback1</InterfaceName>
        </Naming>
      </InterfaceConfiguration>
    </InterfaceConfigurationTable>
  </Configuration>
</Get>
</Request>

Sample XML Minimum Response from a Router (ItemNotFound)

<?xml version="1.0"?>
<Response MajorVersion="1" MinorVersion="0">
  <Get ItemNotFound="true">
    <Configuration>
      <InterfaceConfigurationTable MajorVersion="4" MinorVersion="2">
        <InterfaceConfiguration NotFound="true">
          <Naming>
            <Active>act</Active>
            <InterfaceName>Loopback1</InterfaceName>
          </Naming>
        </InterfaceConfiguration>
      </InterfaceConfigurationTable>
    </Configuration>
  </Get>
  <ResultSummary ErrorCount="0" ItemNotFound="true"/> 
</Response>

Sample XML Request from Client Application (ItemNotFoundBelow)

<?xml version="1.0"?>
<Request MajorVersion="1" MinorVersion="0">
<Get>
  <Configuration>
    <InterfaceConfigurationTable>
      <InterfaceConfiguration>
        <Naming>
          <Active>act</Active>
          <InterfaceName>Loopback0</InterfaceName>
        </Naming>
        <Description/>
        <Shutdown/>
        <IPV4Network/>
      </InterfaceConfiguration>
    </InterfaceConfigurationTable>
  </Configuration>
</Get>
</Request>

Sample XML Minimum Response from a Router (ItemNotFoundBelow)

<?xml version="1.0"?>
<Response MajorVersion="1" MinorVersion="0">
  <Get ItemNotFoundBelow="true">
    <Configuration>
      <InterfaceConfigurationTable MajorVersion="4" MinorVersion="2">
        <InterfaceConfiguration>
          <Naming>
            <Active>act</Active>
            <InterfaceName>Loopback0</InterfaceName>
          </Naming>
          <Description>desc-loop0</Description>
          <Shutdown NotFound="true"/>
          <IPV4Network MajorVersion="5" MinorVersion="1">
            <Addresses>
              <Primary>
                <IPAddress>1.1.1.1</IPAddress>
                <Netmask>255.255.0.0</Netmask>
              </Primary>
            </Addresses>
          </IPV4Network>
        </InterfaceConfiguration>
      </InterfaceConfigurationTable>
    </Configuration>
  </Get>
  <ResultSummary ErrorCount="0" ItemNotFoundBelow="true"/> 
</Response>

Operation Type Tags

Following the <Request> tag, the client application must specify the operations to be carried out by the router. Three general types of operations are supported along with the <GetNext> operation for large responses.

Native Data Operation Tags

Native data operations provide basic access to the native management data model. Table 1-4 describes the native data operation tags.

Table 1-4 Native Data Operation Tags 

Native Data Tag
Description

<Get>

Gets the value of one or more configuration, operational, or action data items.

<Set>

Creates or modifies one or more configuration or action data items.

<Delete>

Deletes one or more configuration data items.

<GetVersionInfo>

Gets the major and minor version numbers of one or more components.

<GetDataSpaceInfo>

Retrieves native data branch names.


The XML schema definitions for the native data operation type tags are contained in the schema file native_data_operations.xsd. The native data operations are described further in Chapter 5, "Cisco XML and Native Data Access Techniques."

Configuration Services Operation Tags

Configuration services operations provide more advanced configuration management functions through the Configuration Manager. Table 1-5 describes the configuration services operation tags.

Table 1-5 Configuration Services Operation Tags 

Tag
Description

<Lock>

Locks the running configuration.

<Unlock>

Unlocks the running configuration.

<Load>

Loads the target configuration from a binary file previously saved using the <Save> tag.

<Save>

Saves the target configuration to a binary file.

<Commit>

Promotes the target configuration to the running configuration.

<Clear>

Aborts or clears the current target configuration session.

<Rollback>

Rolls back the running configuration to a previous configuration state.

<GetConfigurationHistory>

Gets a list of configuration events.

<GetConfigurationSessions>

Gets a list of the user sessions currently configuring the box.

<Get ConfigurationCommitList>

Gets a list of commits that were made to the running configuration and can be rolled back.

<ClearConfigurationSession>

Clears a particular configuration session.

<ClearConfigurationInconsistency>

Clears a configuration inconsistency alarm.


The XML schema definitions for the configuration services operation type tags are contained in the schema file config_services_operations.xsd (see Chapter 14, "Cisco XML Schemas").

The configuration services operations are described further in Chapter 2, "Cisco 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.

The XML schema definitions for the CLI tag are contained in the schema file cli_operations.xsd (see Chapter 14, "Cisco XML Schemas").

The CLI operations are described further in Chapter 6, "Cisco 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.

The XML schema definition for the <GetNext> operation type tag is contained in the schema file xml_api_protocol.xsd (see Chapter 14, "Cisco XML Schemas"). For more information about the <GetNext> operation, see Chapter 7, "Cisco XML and Large Data Retrieval."

Alarm Operation Tags

The <Alarm> operation tag registers, unregisters, and receives alarm notifications. Table 1-6 lists the alarm operation tags.

Table 1-6 List of Alarm Operation Tags 

Tag
Description

<Register>

Registers to receive alarm notifications.

<Unregister>

Cancels a previous alarm notification registration.


The XML schema definitions for the alarm operation tags are contained in the schema file alarm_operations.xsd (see Chapter 14, "Cisco XML Schemas").

XML Request Batching

The 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 as a "best effort." For example, in a case where operations 1 through 3 are in the request, even if operation 2 fails, operation 3 is attempted.

If you want to perform two or more <Get> operations, and if the first one might return a large amount of data that is potentially larger than the size of one iterator chunk, you must place the subsequent operations within a separate XML request. If the operations are placed in the same request within the same <Get> tags, for example, potentially sharing part of the hierarchies with the first request, an error attribute that informs you that the operations cannot be serviced is returned on the relevant tags.

For more information, see Chapter 5, "Cisco XML and Native Data Access Techniques."

This 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 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 CommitID="1000000188"/>
  <Get>
    <Operational>
        .
        .
        .
        .
        .
        .
        .
        .
        .
        Get response content returned here
        .
        .
        .
        .
        .
        .
        .
        .
        .
    </Operational>
  </Get>
  <Unlock/>
  <ResultSummary ErrorCount="0"/>
</Response>