Cisco Internet Streamer CDS 3.1 API Guide

Book Contents

Find Matches in This Book

Available Languages

Download Options

Book Title

Cisco Internet Streamer CDS 3.1 API Guide

Chapter Title

Proximity Engine SOAP APIs

PDF - Complete Book (975.0 KB) PDF - This Chapter (143.0 KB)
View with Adobe Reader on a variety of devices

Results

Chapter: Proximity Engine SOAP APIs

Routing Concepts and Overview
- Terminology
Proximity SOAP API Actions
- rate API
- Fault Message
Proximity Engine WSDL File

Proximity Engine SOAP APIs

This chapter provides an overview of the Proximity Engine, describes the SOAP (Simple Object Access Protocol) APIs exposed by the Proximity Engine, and presents the Web Service Definition Language (WSDL) file used by Proximity Engine to define proximity services. This chapter contains the following sections:

•Routing Concepts and Overview

•Proximity SOAP API Actions

•Proximity Engine WSDL File

Routing Concepts and Overview

You should be familiar with the basics of IP routing and routing protocols, such as Open Shortest Path First (OSPF), Intermediate System-to-Intermediate System (IS-IS), and Border Gateway Protocol (BGP). Each Proximity Engine operates in an IP routing domain where the Interior Gateway Protocol (IGP) or BGP is used to distribute routing information across the domain.

Routers running OSPF or IS-IS establish adjacencies with their directly connected neighbors and exchange their connectivity view (that is, each router advertises its visibility about its adjacencies). Advertisements are flooded throughout the whole routing area and each router stores each received advertisement in a link-state database (LSDB).

The LSDB contains the topology of the whole network and each router uses it in order to compute the Shortest Path Tree and the Routing Information Base (RIB) that contains each known IP prefix in the network and its corresponding next-hop.

Each Proximity Engine leverages the LSDB in order to deliver a proximity service to its clients (Service Routers [SRs]). In order to build the LSDB, the Proximity Engine establishes adjacencies with routers running IGP. In the absence of Proximity Engine IGP peering and an LSDB, the Proximity Engine can still leverage the BGP attributes to deliver a proximity service.

Terminology

An SR sends a proximity request to a Proximity Engine. The proximity request specifies a source IP address and a set of one or more target IP addresses. The following terminology is used for these items:

•Proximity source address (PSA)—IP address from which the proximity needs to be computed.

•Proximity target address (PTA)—IP address to which (from the PSA) proximity has to be computed.

•Proximity target list (PTL)—List of PTAs that need to be evaluated (that is, the proximity from each of these proximity target addresses to the proximity source address needs to be computed).

•Ranking depth—Integer number that determines the length of the ranking list. For example, an SR can request the proximity of 10 nodes out of a PTL of 20 IP addresses.

The scope of the proximity service is to determine the distance between two IP addresses in a routing area. The SR requests the Proximity Engine to rank a list of IP addresses (PTL) based on the individual distance of each PTA from the PSA.

The Proximity function takes into account:

•Routing topology

•Inter-Autonomous System (AS) reachability

•Optimal path taken by the requested data

Proximity SOAP API Actions

Note The Proximity Engine APIs are available on the CDE205 and CDE220-2G2 platforms.

The Proximity Engine exposes a SOAP interface on port 7003. The SOAP interface of the Proximity Engine implements a rate operation to calculate the proximity rating of a group of PTAs. For additional information on the services of the SOAP interface, see the "Proximity Engine WSDL File" section.

Note The SOAP API and associated port 7003 are only available when proximity-based routing is enabled on the SR.

Note The Proximity Engine implements a legacy group operation to return grouping information for a PSA. This operation may be required in a future release, but is not required in the current release because the rate operation returns grouping information for the PSA and the PTAs. The group operation is not specified in this document.

rate API

Requests the Proximity Engine to calculate the proximity of a list of PTAs to a PSA.

Request

The following are the input parameters of the rate request:

•_client—String representing the IP address of the PSA in the format of A.B.C.D.

•_destinations—PTL representing the list of PTAs.

•_category—Type of proximity service requested. Currently, the Proximity Engine only supports network-routing-based proximity which is represented by a value of 2.

•_resultCount—Number of results (that is, PTAs) the client requests to be returned. It refers to Ranking Depth concept described in the "Routing Concepts and Overview" section.

The rate operation is invoked by sending the following input message:

struct ns1__rate

        char *_client;

        struct ns2__ArrayOfJavaLangstring_USCOREliteral *_destinations;

        int _category;

        int _resultCount;

};

The array pointed to by the '_destinations' parameter is represented by an array in the following format:

struct ns2__ArrayOfJavaLangstring_USCOREliteral

        int __sizeJavaLangstring;

        char **JavaLangstring;

};

Request Example

The following section shows an example of a rate request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:prox="http://com/cisco/topos/proximity" xmlns:java="java:com.cisco.topos.proximity">

   <soapenv:Header/>

   <soapenv:Body>

      <prox:rate>

         <client>209.165.201.1</client>

         <destinations>

            <!--Zero or more repetitions:-->

            <java:JavaLangstring>209.165.201.10</java:JavaLangstring>

            <java:JavaLangstring>209.165.201.8</java:JavaLangstring>

            <java:JavaLangstring>209.165.201.11</java:JavaLangstring>

            <java:JavaLangstring>209.165.201.16</java:JavaLangstring>

            <java:JavaLangstring>209.165.201.5</java:JavaLangstring>

            <java:JavaLangstring>209.165.201.7</java:JavaLangstring>

         </destinations>

         <category>2</category>

         <resultCount>100</resultCount>

      </prox:rate>

   </soapenv:Body>

</soapenv:Envelope>

Response

The following are the output parameters of the rate response:

•Address—IP address of the PTA.

•Masklen—Prefix length of the subnet to which the PTA IP Address belongs.

•GroupId (optional)—Configured group for each IP address. For example, AS number, Masklen, or a community. Currently, the Proximity Engine does not return an Group Id.

•Rating—Proximity rating of the PTA based on the proximity algorithm.

The data structure of the rate response is as follows:

struct ns1__rateResponse

        struct ns2__ArrayOfServiceRatedAddress_USCOREliteral *_RatedAddressArray;

};

The ranked PTAs are returned in the ServiceRatedAddress array pointed to by the RatedAddressArray in the following format:

struct ns2__ArrayOfServiceRatedAddress_USCOREliteral

        int __sizeServiceRatedAddress;

        struct ns2__ServiceRatedAddress *ServiceRatedAddress;

};

Note The first member of the ServiceRatedAddress array is the PSA.

Each member of the ServiceRatedAddress is returned in the following format:

struct ns2__ServiceRatedAddress

        char *Address;

        int Masklen;

        LONG64 *GroupId;

        int Rating;

};

The array of PTAs is returned in ranked order of ascending rating with the PSA being the first member of the array.

Response Example

The following section shows an example of a rate response:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:ns2="java:com.cisco.topos.proximity" 
xmlns:ns1="http://com/cisco/topos/proximity">

   <SOAP-ENV:Header/>

   <SOAP-ENV:Body>

      <ns1:rateResponse>

         <RatedAddressArray>

            <ns2:ServiceRatedAddress>

               <ns2:Address>209.165.201.1</ns2:Address>

               <ns2:Masklen>32</ns2:Masklen>

               <ns2:Rating>0</ns2:Rating>

            </ns2:ServiceRatedAddress>

            <ns2:ServiceRatedAddress>

               <ns2:Address>209.165.201.5</ns2:Address>

               <ns2:Masklen>32</ns2:Masklen>

               <ns2:Rating>10</ns2:Rating>

            </ns2:ServiceRatedAddress>

            <ns2:ServiceRatedAddress>

               <ns2:Address>209.165.201.7</ns2:Address>

               <ns2:Masklen>32</ns2:Masklen>

               <ns2:Rating>10</ns2:Rating>

            </ns2:ServiceRatedAddress>

            <ns2:ServiceRatedAddress>

               <ns2:Address>209.165.201.8</ns2:Address>

               <ns2:Masklen>20</ns2:Masklen>

               <ns2:Rating>20</ns2:Rating>

            </ns2:ServiceRatedAddress>

            <ns2:ServiceRatedAddress>

               <ns2:Address>209.165.201.10</ns2:Address>

               <ns2:Masklen>129</ns2:Masklen>

               <ns2:Rating>70</ns2:Rating>

            </ns2:ServiceRatedAddress>

            <ns2:ServiceRatedAddress>

               <ns2:Address>209.165.201.11</ns2:Address>

               <ns2:Masklen>129</ns2:Masklen>

               <ns2:Rating>70</ns2:Rating>

            </ns2:ServiceRatedAddress>

            <ns2:ServiceRatedAddress>

               <ns2:Address>209.165.201.16</ns2:Address>

               <ns2:Masklen>129</ns2:Masklen>

               <ns2:Rating>70</ns2:Rating>

            </ns2:ServiceRatedAddress>

         </RatedAddressArray>

      </ns1:rateResponse>

   </SOAP-ENV:Body>

</SOAP-ENV:Envelope>

Fault Message

The gSOAP server supports a number of faults, each representing a different error scenario. In most cases, a fault is simply a string describing a fault condition. Table 8-1 presents the list of faults specific to the Proximity Engine and provides an explanation for each fault.

Table 8-1 Proximity Engine Faults
Proximity Engine Fault	Explanation
Proximity Service Failed: Urib¹ failed to send request to protocol	There is a communication problem between the URIB and the IGP or BGP daemons.
Proximity Service Failed: Urib failed to receive from protocol	There is a communication problem between the URIB and the IGP or BGP daemons.
Proximity Service Failed: Route lookup failed in URIB	The PSA cannot be resolved by URIB. That is, the PSA cannot be found in the IP routing table.
Proximity Service Failed: Unrecognized exception	An unknown error has occurred.

¹URIB = unicast routing information base

Fault Response

The data structures of a SOAP fault response are as follows:

/* SOAP Fault Code: */

struct SOAP_ENV__Code

        char *SOAP_ENV__Value;

        struct SOAP_ENV__Code *SOAP_ENV__Subcode;

};

/* SOAP-ENV:Detail */

struct SOAP_ENV__Detail

        int __type;

        void *fault;            char *__any;

};

/* SOAP-ENV:Reason */

struct SOAP_ENV__Reason

        char *SOAP_ENV__Text;

};

/* SOAP Fault: */

struct SOAP_ENV__Fault

        char *faultcode;

        char *faultstring;

        char *faultactor;

        struct SOAP_ENV__Detail *detail;

        struct SOAP_ENV__Code *SOAP_ENV__Code;

        struct SOAP_ENV__Reason *SOAP_ENV__Reason;

        char *SOAP_ENV__Node;

        char *SOAP_ENV__Role;

        struct SOAP_ENV__Detail *SOAP_ENV__Detail;

};

A redirect fault occurs when the Proximity Engine does not consider itself the most appropriate Proximity Engine to service the request, and redirects the proximity client to a set of Proximity Engines it considers more appropriate.

Redirect Response

The Proximity Engine uses the following redirect response data structure wrapped inside the SOAP_ENV_FAULT data structure to send a redirect fault:

struct ns2__RedirectResponse

/// @brief PSA grouping info.

/// Element psa of type java:com.cisco.topos.proximity":ServiceGroupRange.

    struct ns2__ServiceGroupRange*       psa                            1;  ///< Required 
element.

/// @brief SG Endpoints for the redirect.

/// Element EndPoints of type "java:com.cisco.topos.proximity":EndPoints.

    struct ns2__EndPoints*               EndPoints                      1;  ///< Required 
element.

};

The Proximity Engine returns as part of this fault the group information of the PSA and the list of EndPoints. The data structure of the PSA group information is as follows:

struct ns2__ServiceGroupRange

        char *Address;

        int Masklen;

        LONG64 *GroupId;

};

The Proximity Engine also returns as part of this fault the list of EndPoints containing the list of IP addresses of other Proximity Engines in the network that are more appropriate for this proximity request. The data structure of the list of EndPoints is as follows:

struct _ns2__EndPoints

        int __sizeEndPoint;

        char **EndPoint;

};

Proximity Engine WSDL File

A WSDL file is an XML-formatted file that describes the details as a web service and specifies the operations it knows how to perform. The WSDL file for the SOAP interface of the Proximity Engine is as follows:

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

<s0:definitions name="NetworkProximityServiceDefinitions" 
targetNamespace="http://com/cisco/topos/proximity" xmlns="" 
xmlns:s0="http://schemas.xmlsoap.org/wsdl/" xmlns:s1="http://www.w3.org/2001/XMLSchema" 
xmlns:s2="java:com.cisco.topos.proximity" xmlns:s3="http://com/cisco/topos/proximity" 
xmlns:s4="http://schemas.xmlsoap.org/wsdl/soap/">

  <s0:types>

    <xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" 
targetNamespace="java:com.cisco.topos.proximity" 
xmlns:xs="http://www.w3.org/2001/XMLSchema">

        <xs:complexType name="ServiceRatedAddress">

          <xs:annotation>

            <xs:documentation>Rated IP address.</xs:documentation>

          </xs:annotation>

          <xs:sequence>

              <xs:element minOccurs="1" name="Address" nillable="false" type="xs:string">

                <xs:annotation>

                  <xs:documentation>Get IP address.</xs:documentation>

                </xs:annotation>

              </xs:element>

              <xs:element minOccurs="1" name="Masklen" nillable="false" type="xs:int">

                <xs:annotation>

                  <xs:documentation>Get subnet masklen.</xs:documentation>

                </xs:annotation>

              </xs:element>

                <xs:element minOccurs="0" name="GroupId" nillable="false" type="xs:long">

                <xs:annotation>

                  <xs:documentation>Get group Id.</xs:documentation>

                </xs:annotation>

              </xs:element>

            <xs:element minOccurs="1" name="Rating" nillable="false" type="xs:int">

              <xs:annotation>

                <xs:documentation>Get rating.</xs:documentation>

              </xs:annotation>

            </xs:element>

          </xs:sequence>

        </xs:complexType>

      <xs:complexType name="ServiceGroupRange">

        <xs:annotation>

          <xs:documentation>Group Id with addresss range.</xs:documentation>

        </xs:annotation>

        <xs:sequence>

          <xs:element minOccurs="1" name="Address" nillable="false" type="xs:string">

            <xs:annotation>

              <xs:documentation>Get IP address.</xs:documentation>

            </xs:annotation>

          </xs:element>

          <xs:element minOccurs="1" name="Masklen" nillable="false" type="xs:int">

            <xs:annotation>

              <xs:documentation>Get subnet masklen.</xs:documentation>

            </xs:annotation>

          </xs:element>

            <xs:element minOccurs="0" name="GroupId" nillable="false" type="xs:long">

            <xs:annotation>

              <xs:documentation>Get group Id.</xs:documentation>

            </xs:annotation>

          </xs:element>

        </xs:sequence>

      </xs:complexType>

      <xs:element name="psa" type="java:ServiceGroupRange" 
xmlns:java="java:com.cisco.topos.proximity">

            <xs:annotation>

                <xs:documentation>PSA grouping info</xs:documentation>

              </xs:annotation>

      </xs:element>

        <xs:complexType name="EndPoints">

            <xs:annotation>

                <xs:documentation>SG EndPoints for the redirect</xs:documentation>

            </xs:annotation>

            <xs:sequence>

                <xs:element name="EndPoint" maxOccurs="unbounded" minOccurs="1" 
nillable="false" type="xs:string"/>

            </xs:sequence>

        </xs:complexType>

        <xs:complexType name="RedirectResponse">

          <xs:annotation>

            <xs:documentation>Redirect response.</xs:documentation>

          </xs:annotation>

          <xs:sequence>

              <xs:element maxOccurs="1" minOccurs="1" name="psa" nillable="false"

              type="java:ServiceGroupRange"

              xmlns:java="java:com.cisco.topos.proximity">

                <xs:annotation>

                  <xs:documentation>PSA grouping info.</xs:documentation>

                </xs:annotation>

              </xs:element>

              <xs:element maxOccurs ="1" minOccurs="1" name="EndPoints" nillable="false"

              type="java:EndPoints" xmlns:java="java:com.cisco.topos.proximity">

                <xs:annotation>

                  <xs:documentation>SG Endpoints for the redirect.</xs:documentation>

                </xs:annotation>

              </xs:element>

          </xs:sequence>

        </xs:complexType>

      <xs:complexType name="ArrayOfServiceRatedAddress_literal">

        <xs:sequence>

          <xs:element maxOccurs="unbounded" minOccurs="0" name="ServiceRatedAddress" 
nillable="true" type="java:ServiceRatedAddress" 
xmlns:java="java:com.cisco.topos.proximity"/>

        </xs:sequence>

      </xs:complexType>

      <xs:element name="ArrayOfServiceRatedAddress_literal" 
type="java:ArrayOfServiceRatedAddress_literal" 
xmlns:java="java:com.cisco.topos.proximity"/>

      <xs:complexType name="ArrayOfServiceGroupRange_literal">

        <xs:sequence>

          <xs:element maxOccurs="unbounded" minOccurs="0" name="ServiceGroupRange" 
nillable="true" type="java:ServiceGroupRange" 
xmlns:java="java:com.cisco.topos.proximity"/>

        </xs:sequence>

      </xs:complexType>

      <xs:element name="ArrayOfServiceGroupRange_literal" 
type="java:ArrayOfServiceGroupRange_literal" xmlns:java="java:com.cisco.topos.proximity"/>

      <xs:complexType name="ArrayOfJavaLangstring_literal">

        <xs:sequence>

          <xs:element maxOccurs="unbounded" minOccurs="0" name="JavaLangstring" 
nillable="true" type="xs:string"/>

        </xs:sequence>

      </xs:complexType>

      <xs:element name="ArrayOfJavaLangstring_literal" 
type="java:ArrayOfJavaLangstring_literal" xmlns:java="java:com.cisco.topos.proximity"/>

    </xs:schema>

  </s0:types>

  <s0:message name="rate">

    <s0:part name="client" type="s1:string"/>

    <s0:part name="destinations" type="s2:ArrayOfJavaLangstring_literal"/>

    <s0:part name="category" type="s1:int"/>

    <s0:part name="resultCount" type="s1:int"/>

  </s0:message>

  <s0:message name="rateResponse">

    <s0:part name="RatedAddressArray" type="s2:ArrayOfServiceRatedAddress_literal"/>

  </s0:message>

  <s0:message name="group">

    <s0:part name="addresses" type="s2:ArrayOfJavaLangstring_literal"/>

  </s0:message>

  <s0:message name="groupResponse">

    <s0:part name="GroupRangeArray" type="s2:ArrayOfServiceGroupRange_literal"/>

  </s0:message>

  <s0:portType name="NetworkProximityPortType">

    <s0:operation name="rate" parameterOrder="client destinations category resultCount">

      <s0:input message="s3:rate"/>

      <s0:output message="s3:rateResponse"/>

    </s0:operation>

    <s0:operation name="group" parameterOrder="addresses">

      <s0:input message="s3:group"/>

      <s0:output message="s3:groupResponse"/>

    </s0:operation>

  </s0:portType>

  <s0:binding name="NetworkProximityServiceSoapBinding" 
type="s3:NetworkProximityPortType">

    <s4:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/>

    <s0:operation name="rate">

      <s4:operation soapAction="" style="rpc"/>

      <s0:input>

        <s4:body namespace="http://com/cisco/topos/proximity" parts="client destinations 
category resultCount" use="literal"/>

      </s0:input>

      <s0:output>

        <s4:body namespace="http://com/cisco/topos/proximity" parts="RatedAddressArray" 
use="literal"/>

      </s0:output>

    </s0:operation>

    <s0:operation name="group">

      <s4:operation soapAction="" style="rpc"/>

      <s0:input>

        <s4:body namespace="http://com/cisco/topos/proximity" parts="addresses" 
use="literal"/>

      </s0:input>

      <s0:output>

        <s4:body namespace="http://com/cisco/topos/proximity" parts="GroupRangeArray" 
use="literal"/>

      </s0:output>

    </s0:operation>

  </s0:binding>

  <s0:service name="NetworkProximityService">

    <s0:port binding="s3:NetworkProximityServiceSoapBinding" 
name="NetworkProximityServicePort">

      <s4:address location="http://localhost:7003/"/>

    </s0:port>

  </s0:service>

</s0:definitions>

Was this Document Helpful?

Feedback

Contact Cisco

Open a Support Case
(Requires a Cisco Service Contract)

Cisco Internet Streamer CDS 3.1 API Guide

Results

Chapter: Proximity Engine SOAP APIs

Proximity Engine SOAP APIs

Routing Concepts and Overview

Terminology

Proximity SOAP API Actions

rate API

Fault Message

Proximity Engine WSDL File

Was this Document Helpful?

Contact Cisco

Related Cisco Community Discussions

Share