Cisco Internet Streamer CDS 3.1 API Guide
Chapter: Proximity Engine SOAP APIs
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
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.
|
|
|
|---|---|
Proximity Service Failed: Urib1 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. |
1 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>
Feedback