1. No category

XML API Dev Guide
Copyright  2009 by Extreme Networks
All Rights Reserved
Extreme Networks, Inc.
3585 Monroe St., Santa Clara, CA 95051
(408) 579-2800
No part of this document may be reproduced in any form without the prior written
permission of Extreme Networks, Inc.
REVISION HISTORY
Date
03/18/09
Revision Description
Initial version
Changed By
Suresh Balineni
REVIEWED BY:
Date
Name
Approved
CONTENTS
1
INTRODUCTION..................................................................................................... 4
2
XML API OVERVIEW ............................................................................................ 4
2.1
OVERVIEW OF XML API INFRASTRUCTURE IN EXOS ......................................... 4
2.2
XML API DESIGN ............................................................................................... 5
2.2.1
Design Principles ........................................................................................ 5
2.2.2
XML API Object Modeling ......................................................................... 6
3
XML API DEVELOPMENT ................................................................................. 10
3.1
UNDERSTANDING WSDL/XML SCHEMA .......................................................... 10
3.2
GUIDELINES FOR WRITING XML SCHEMA.......................................................... 14
3.2.1
Naming Guidelines.................................................................................... 14
3.2.2
Defining XML Schema .............................................................................. 17
4
XML API IMPLEMENTATION .......................................................................... 22
4.1.1
Steps .......................................................................................................... 22
4.1.2
Issues you might phase.............................................................................. 24
4.2
INTEROPERABILITY ............................................................................................ 26
4.3
EXOS REFERENCE IMPLEMENTATIONS, XML SCHEMA/WSDL FILES ............... 26
5
XML TESTING ...................................................................................................... 26
5.1
5.2
6
PROCESS ................................................................................................................ 27
6.1
6.2
6.3
7
UNIT TESTING .................................................................................................... 26
INTEGRATION TESTING ...................................................................................... 27
SET UP ............................................................................................................... 28
XML REVIEW GUIDELINES ................................................................................ 28
RELEASE SIGN OFF ............................................................................................ 30
APPENDIX .............................................................................................................. 30
7.1
REFERENCES ...................................................................................................... 30
7.2
FAQ................................................................................................................... 31
7.2.1
General ..................................................................................................... 31
7.2.2
Implementation ......................................................................................... 32
7.2.3
Debug, Test and Examples........................................................................ 36
7.2.4
Miscellaneous ........................................................................................... 37
1 Introduction
This document describes XML API development process that includes following:
1. XML API Overview
2. XML API Design
3. XML elements/attributes naming guidelines
4. XML Schema writing guidelines
5. Internal Mapping Guidelines
6. XML schema review guidelines
7. XML API Implementation procedure.
8. Interoperability
9. References
10. FAQ
2 XML API Overview
2.1 Overview of XML API Infrastructure in EXOS
EPI Center
Screen Play
Third Party
Web App
EXOS
HTTP Module
XMLD Module
CfgMgr
Backend
Process
Backend
Process
4
XML API Infrastructure provides capability to monitor/configure the EXOS switch from
EPI Center/Screen Play or from any other third party application over HTTP.
The communication between external client and EXOS box will happen in XML format
over SOAP transport protocol. SOAP is a transport protocol for accessing Web Services.
A web service is a method which can be invoked from a remote http client. WSDL is a
language for defining Web Services. EXOS has a set of well defined web services such as
GET /SET/DELETE/CREATE. These methods take EXOS Objects as Input. XML
Schema is used for defining EXOS Objects. This is similar to “.obj” infrastructure in
EXOS. “.obj” format is internal to EXOS where as XML Schema is standard format for
defining the structure of objects/associations and containments. External client programs
can invoke these objects directly using WSDL calls.
Typical flow between External Client and EXOS:
1.
External Web Client Sends SOAP Request to EXOS box.
2.
HTTP Server in EXOS receives the request
3.
HTTP module finds it’s an XML Request and passes it to XMLD Module.
4.
XMLD validates authentication, returns error if failed.
5.
XMLD Module parses the request and constructs one or more backend
.obj commands.
6.
XMLD sends a series of requests to backend applications
7.
XMLD receives data from backend applications
8.
XMLD constructs external data (converts internal data into external
schema format).
9.
XMLD sends the data/error back to HTTP Module.
10.
HTTP sends data/error back to client.
2.2 XML API Design
This section describes more about designing API Object.
2.2.1 Design Principles
1.
XML API Object Design should follow object-oriented principles.
5
2.
Define a set of Uses Cases from the perspective of how a External Client
is going to interact with EXOS using APIs. It is recommended to define
flow charts/sequence diagrams for the Uses Cases.
3.
Analyze uses cases and find out Objects which are involved in Uses
Cases. Classify all objects in terms of Concrete Objects and Containment
Objects. Concrete object is the one which a Client directly queries where
as containment object is the one which is part of another object. Client can
not interact with contained object directly with out parent object. It is
recommended to define Object-Interaction diagram.
4.
Define associations (such as aggregation, composition, inheritance)
between these objects.
5.
Define attributes for each Object.
6.
Define Properties for each attributes. Properties should include the type,
range, and possible values.
2.2.2 XML API Object Modeling
In EXOS XML API, XML Schemas contains the definition of Managed Objects and
WSDL contains operations which can be performed on Managed objects. SOAP is a
transport protocol for calling WSDL operations from a remote client over
HTTP/SSH/Telnet.
Managed Object is the one which is exposed via XML API. “Containment Object” is the
one which is contained in another object and can not be accessed directly from API with
out its parent object.
In general, every Managed object has a specific set of characteristics.
- Name
- Type
- Set of attributes
- Containment objects, if any
- Inheritance properties
- Set of predefined operations
- Version
Attributes will have properties
- Name
- Type (Primitive or derived)
- Access Rights
- Status
- Version
- Number of Occurrences of this attribute can be present on the object instance.
6
-
Enumerated values, if any
Operations in Network Management are generally classified as Get, Set, Create, Delete,
Add, and Remove.
In EXOS XML API framework, apart from Managed object definition we need additional
information for every object/attribute to map into internal object/attribute.
The following describes the required mapping parameters for an Object and for an
attribute.
XML API Object will have following properties:
•
•
•
•
•
•
•
•
name
- Name of the object (external Object Name)
exos_module
- EXOS Internal Module name
exos_obj
- EXOS Internal Object Name
index_attributes - Index attributes for this attribute
operations
- Only for concrete objects
version
- Version introduced this object
set of attributes
set of containment objects
Attribute will have following properties:
•
•
•
•
•
•
•
•
•
•
name - Name of the attribute
type - Type of the attribute, type could be one of predefined
Standard types or a user defined type.
access - Access Rights for the attribute, must be specified, IRW
exos_obj - Name of the EXOS internal object, this is used to
override the EXOS object specified at object level. It is Optional.
exos_var - name of the EXOS internal name. (Must be same as
the one defined in EXOS internal object definition), if not defined
exos_var name will be same as attribute name.
exos_module – name of the EXOS module, this is used to override
the EXOS module specified at object level, optional.
default - default value of this attribute to be set or return, if not
present
Status
- Status of the attribute, as of now allowed value is
'deprecated'. This is Optional. This need not be specified unless to
deprecate the attribute.
version - EXOS Version in which this attribute is introduced.
occurrences - Minimum/Maximum number of instances of this
attribute for this object. Optional. Default will be SET to 0...1.
7
•
Range – Min and Max values for integer and floating type
attributes.
During the design process, API developer should represent the Object modeling using the
following syntax.
object <objName>
{
properties
{
type: concrete;
//”concrete” Indicates API Exposed Object, “abstract”
means it is not accessed from API directly and it should
be part of another object.
exos_module: module1;
exos_object: exosObj1;
index_attributes: attr1, attr2;
version: 12.2;
operations : get, set, create
documentation
{
“This Object is used to….
………..configuration”;
};
};
attributes
{
attr1
{
type: string;
access: IRW;
exos_var: exosVar1;
version: 12.2;
};
attr2
{
type: int;
access: RW;
exos_var: exosVar2;
exos_obj: exosObj2;
version: 12.1;
occurrences : [0..8] ;
range : [1..1024];
documentation
8
{
“attribute for configuration of ……vlan module”;
};
};
attr3
{
type: qosEnum;
access: R;
version: 12.2
documentation
{
“…..”;
};
enumMap
{
<enum1> : <internal value>
<enum2> : <internal_value>
--}
};
};
contains
{
objectName1
{
type : objectName1Type
attributes
{
attr1
{
//
};
};
};
};
};
/* This is used to define any Enumeration data types, attributes can be of this enum type
*/
type enum <name>
{
<enum1>;
<enum2>;
9
};
Note – 2: XML API FS Document should contain the API modeling using above
syntax.
Note – 2: Template for modeling object is available in
“/code/cfgmgmt/xmld/src/templates/template_api_model.mdl”.
3 XML API Development
3.1
Understanding WSDL/XML Schema
We need to represent Object Model and Operations in XML Schemas and WSDL. We
have a common set of global operations for all objects and are not required to define for
every object. But we need to associate whether a particular operation can be performed
on a given object.
XML Schema is a generic language which is used to define the General Syntax of any
XML document and in our framework we use only a small set of Schema constructs and
there is clear format/rules in using those constructs.
WSDL - Web Services Description Language
Set of API Method calls exposed to client application, EXOS has standard set of API
calls and are defined in “switch.wsdl”. The following APIs are defined in
switch.wsdl.
-
Get (ExosBase Object, Action[“”, “next”], Filter parameters);
Set (ExosBase Object, Filter parameters);
Delete (ExosBase Object, Filter parameters);
Create (ExosBase Object, Filter parameters);
Please note that these are standard APIs exposed to External clients; you don’t have
to modify “switch.wsdl” for any Object that you introduce.
EXOS Objects are input arguments to these API calls. XML Schema should be used
for defining EXOS Objects.
XML Schema
Now, it is understood that XML Schema is used for defining EXOS Objects.
Following describes the basic overview and constructs of XML Schema.
XML Schema describes the structure of an XML document or in other words XML
Document can be an instance of an XML Schema.
10
The XML Schema language is also referred to as XML Schema Definition (XSD).
For tutorials on XML Schema please refer
http://www.w3schools.com/Schema/default.asp
XML Schema has standard constructs for defining types such as Simple types,
Complex types and Elements. Following are few XML Constructs which we use for
defining EXOS Objects
1.
Simple Type
Generally Simple Types are used to define simple data types which are
used for defining an element. XSD provides standard set of primitive data
types such as int, string, Boolean. Schema developer can define any
number of simple data types and later they can be used for defining
elements. ENUMs are defined using SimpleType construct.
Example:
<xsd:simpleType name="NodeStates">
<xsd:annotation>
<xsd:documentation>
Enumeration for node states.
</xsd:documentation>
</xsd:annotation>
<xsd:restriction base="xsd:string">
<xsd:enumeration value="unknown"/>
<xsd:enumeration value="Disabled"/>
<xsd:enumeration value="Failed"/>
<xsd:enumeration value="Overflow"/>
<xsd:enumeration value="Listening"/>
<xsd:enumeration value="Stabilizing"/>
<xsd:enumeration value="Waiting"/>
<xsd:enumeration value="Active"/>
<xsd:enumeration value="na"/>
</xsd:restriction>
</xsd:simpleType>
In this example, we have defined a simpleType with name “NodeStates”. Later,
“NodeStates” can be used as type for defining an attribute of Object.
2.
Complex Type
Complex Type is used to define a Complex Structure and it contains one or more elements.
Schema Developer can define any number of complex data types. This complex data type can
be used to define objects and note that same complex data type can be used to define multiple
Objects. This is analogous to “typedef struct”.
Example:
<xsd:complexType name="QoSProfileInfo">
<xsd:annotation>
<xsd:documentation>
QoS profile information.
</xsd:documentation>
</xsd:annotation>
<xsd:sequence>
<xsd:element name="qos" type="QoSProfiles" minOccurs="0"/>
<xsd:element name="minBw" type="common:uint32_t" minOccurs="0"/>
11
<xsd:element name="maxBw" type="common:uint32_t" minOccurs="0"/>
<xsd:element name="priority" minOccurs="0">
<xsd:simpleType>
<xsd:restriction base="xsd:byte">
<xsd:minExclusive value="0"/>
<xsd:maxExclusive value="7"/>
</xsd:restriction>
</xsd:simpleType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
In EXOS, we use Complex Data types in two different ways.
-
-
Containment Complex Data Type
This is used only for defining elements in another Complex
Data Type. API methods can not have these types as
parameters.
API Complex Data Type
API methods will have parameters of only this type.
EXOS has a way to differentiate between Containment Complex
Data Type and API used Complex Data Type. All API used
Complex data types should be inherited from EXOS base Type and
where as Complex Data Type should not be inherited from EXOS
Base Type. EXOS Base is Complex Data Type, all API methods
will have parameters of Type EXOS Base. Please note that in
EXOS implementation only complex data types can be exposed via
API.
3. Element
This is used to define the actual instance of a type. i.e. to define an
attribute/object.
Example:
<xsd:complexType name="PortConfig">
<xsd:complexContent>
<xsd:extension base="common:ExosBase">
<xsd:sequence>
<xsd:element name="portList" type="common:StringLen8" minOccurs="0">
</xsd:element>
<xsd:element name="smartRedundancyEnabled" type="common:TrueFalse"
minOccurs="0">
</xsd:element>
<xsd:element name="type" type="xsd:string" minOccurs="0">
</xsd:element>
<xsd:element name="virtualRouter" type="common:StringLen32" minOccurs="0">
</xsd:element>
<xsd:element name="eQosProfile" type="QoSProfileInfo" minOccurs="0"
maxOccurs="8">
</xsd:element>
</xsd:sequence>
</xsd:extension>
12
</xsd:compplexContent>
</xsd:complexType>
Description of above example:
1. “PortConfig” is a complex data type inherited from ExosBase type and hence
it is an API exposed Object.
2. “<xsd:complexContent> is an XML Schema syntax for representing
inheritance. If you want to inherit from other Complex Data type, you should
use the same Syntax. Please note that, inheritance can be used for defining any
non API exposed Complex Data types. You can have any number of
inheritance levels but you can not a data type inheriting from multiple
Complex data types, i.e. multiple inheritances is not allowed where as
hierarchical inheritance is allowed.
3. <xsd:sequence> is an XML Schema construct used to specify the sequence of
elements in which they occur. If you use <xsd:sequence> means element order
is strict and an instance of this type(XML Document) should have the same
sequence of XML elements. Please note that, once the object is released and if
you want add any new elements you should add at the end of the object
definition.
4. <xsd:element> is an XML Schema construct to define an attribute. In the
example, “PortConfig” data type have elements “portList” of type
“common:StringLen8”, "smartRedundancyEnabled” of type
“common:TrueFalse” etc.
5. You can include data types across different XSDs. The following is the syntax
to include XSDs.
<xsd:import
namespace=”http://www.extremenetworks.com/XMLSchema/xos/common”
schemaLocation="./common.xsd"/
In the above example, “common:TrueFalse” means “TrueFalse” is defined in
name space “common”. Common.xsd has namespace called “common” under
which “TrueFalse” is defined.
Generally namespaces follows the URI syntax to uniquely identify the Schema
universally. This is to avoid any conflicts with other XSD data types since client
application can have different XSDs from different vendors.
You can find following construct in common.xsd for defining namespaces:
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:tns="http://www.extremenetworks.com/XMLSchema/xos/common
" xmlns="http://www.extremenetworks.com/XMLSchema/xos/common"
targetNamespace="http://www.extremenetworks.com/XMLSchema/xos/c
ommon" version="A.B.C.D">
13
6. In the example, “eQoSProfile” is an element of PortConfig and is a complex
data type “QoSProfileInfo”. QoSProfileInfo is a non API exposed complex data
type and is used for defining complex elements in another complex data type.
You can visualize this as structure within another structure.
6. “minOccurs” indicates the minimum occurrences of the element in the
instance(XML Document) of the data type. “0” indicates this is optional
parameter.
7. “maxOccurs” indicates maximum occurrences of the element in the instance of
the data type. In the example “eQosProfile” has “maxOccurs” ‘8’ means
“PortConfig” object can have maximum ‘8’ eQosProfile elements.
3.2
Guidelines for writing XML Schema
3.2.1 Naming Guidelines
1. Element or attribute name should start with character not with number. This is not
allowed in XML schema. So if there is requirement that name should start with
number add n prefix.
Examples:
<xsd:element name=”802.1dEnabled” type=”xsd:Boolean” /> is inconsistent.
<xsd:element name=”n8021dEnabled” type=”xsd:Boolean” /> is correct.
2. Element or attribute name should start with small character.
Example:
<xsd:element name=”Speed” type=”xsd:integer”> is inconsistent
<xsd:element name=”speed” type=”xsd:integer”> is correct
<xsd:element name=”QOS” type=”xsd:string”> is inconsistent
<xsd:element name=”qos” type=”xsd:string”> is correct
3. Element or attribute name should follow Camel Case naming convention.
Example:
<xsd:element name=”ipaddress” type=”xsd:string”> is inconsistent.
<xsd:element name=”Ip_address” type=”xsd:string”> is inconsistent.
<xsd:element name=”ipAddress” type=”xsd:integer”> is correct.
4. Element or attribute name should be self explanatory.
Example:
<xsd:element name="highPriCosVal" minOccurs="0"> is inconsistent.
14
<xsd:element name="highPriorityCosVal" minOccurs="0"> is correct.
<xsd:element name="smartRedundancyFlag" type="xsd:boolean" minOccurs="0"> is inconsistent.
<xsd:element name="smartRedundancyEnabled" type="xsd:boolean" minOccurs="0"> is correct.
5. If the type of element or attribute is Boolean then it should be suffix with
Enabled.
Example:
<xsd:element name="smartRedundancyFlag" type="xsd:boolean" minOccurs="0"> is inconsistent.
<xsd:element name="smartRedundancyEnabled" type="xsd:boolean" minOccurs="0"> is correct.
6. Data type definition name should start with the capitol character.
Example:
<xsd:simpleType name="percent">
<xsd:restriction base="xsd:byte">
<xsd:minExclusive value="0"/>
<xsd:maxExclusive value="100"/>
</xsd:restriction>
</xsd:simpleType> is inconsistent
<xsd:simpleType name="Percent">
<xsd:restriction base="xsd:byte">
<xsd:minExclusive value="0"/>
<xsd:maxExclusive value="100"/>
</xsd:restriction>
</xsd:simpleType> is correct.
7. Enumeration data type definition name should be plural and if the name does not
have plural then the name should be suffix with the "Values" word.
Example:
<xsd:simpleType name="FloodingTypes">
<xsd:restriction base="xsd:string">
<xsd:enumeration value="unknown"/>
<xsd:enumeration value="unicast"/>
<xsd:enumeration value="multicast"/>
<xsd:enumeration value="broadcast"/>
<xsd:enumeration value="all"/>
<xsd:enumeration value="n/a"/>
</xsd:restriction>
</xsd:simpleType> is correct.
8. All the enums should have first element as “unknown” and last as “na”. And all
the values should start with small character unless some exception.
Example:
<xsd:simpleType name="FloodingTypes">
<xsd:restriction base="xsd:string">
<xsd:enumeration value="unknown"/>
<xsd:enumeration value="unicast"/>
<xsd:enumeration value="multicast"/>
<xsd:enumeration value="broadcast"/>
<xsd:enumeration value="all"/>
<xsd:enumeration value="na"/>
</xsd:restriction>
15
</xsd:simpleType>
is correct.
9. If any definition is being used by more than two XSDs the definition should be at
some common xsd e.g., common.xsd, l2protocol.xsd, l3protocol.xsd etc.
10. Element or attribute name should not have any restriction. This will helps in the
extensibility. You can put restriction if you are really certain.
Example:
<xsd:element name="burstSize" minOccurs="0">
<xsd:annotation>
<xsd:documentation> </xsd:documentation>
<xsd:appinfo>
<version>EXOS 11.2</version>
</xsd:appinfo>
</xsd:annotation>
<xsd:simpleType>
<xsd:restriction base="xsd:unsignedInt">
<xsd:minInclusive value="64000"/>
<xsd:maxExclusive value="2000000"/>
</xsd:restriction>
</xsd:simpleType>
</xsd:element>
is not consistent
11. As of now, Data types should be unique across all XSD files. Please make sure if
there is a data type with name in another XSD, XMLD module will override one
of these data types. You might need to consider placing common data types in
“common.xsd” schema or change the name of your new data type. Do not change
the existing data type.
12. Common.xsd has set of commonly Data Types – TrueFalse, EnableDisable,
YesNo, IP Address, IP V6 Address, Various String/Integer Types etc. Please
check if you can reuse them.
13. Any Configuration object should have naming <Kind of Object>Config.
Examples:
RadiusConfig
PortConfig
PrivateVlanMemberConfig
GeneralConfiig.
RadiusCfg, FdbCfgInfo are inconsistent.
14. Statistical Object should have naming <Kind of Object>Stats
16
PortErrorStats
PortUtilizationStats
PortQoSStats
PortTrafficStats
15. Parameter name should describe the meaning of its purpose, i.e it should be self
explained.
example: <UserIdentitySummary>
<timeStamp>
</UserIdentitySummary>
In the above example, <timestamp> does not indicate its description, where as
<lastModifiedTime> may be more accurate in this case.
16. Parameter name should not contain the redundant information or parent object
name in it.
Example:
<PortConfig>
<portQosProfile>
</PortConfig>
In the above example, <portQosProfile> name contains Parent Object Name (port)
which is redundant. You would need to name it just “qosProfile”..
3.2.2 Defining XML Schema
1. Follow XML schema components/elements naming guidelines.
2. You need to include “annotation” element for every XML Object/Element which
requires a mapping from external element to internal .OBJ element.
Please note that Annotation contains two elements:
1. Documentation
Here you could mention the documentation about the element/object.
2. App Info
This is used by the XMLD Module to convert external Object/Attribute to
internal .OBJ structures. AppInfo elements are used to convert External
elements to internal XML requests.
a) AppInfo for Object Definitions
Every XML Object will have global AppInfo. This should
contain the following information:
1. Module Name
2. Object Name
17
3. Version
This is to identify the internal module name, object name
and EXOS version in which this object is introduced.
b) AppInfo for simple type elements of an Object.
It is required to provide the internal mappings for an
element. Element AppInfo should contain the following
information.
Access
-
This represents what kind of access this element can have.
This can have READ, WRITE, CREATE, DELETE,
DEPRECATED, INDEX values
Please use the exact words as defined here; this will be
parsed to construct internal commands.
Module Name
-
The process which implement this internal object. Please
note that it is not required to mention “module” name, if the
attribute defined is in same module as Object level.
(Module name must be present at Object element)
Internal Object
-
Internal object defined in .OBJ structure, this is required
object level.
Variable
-
Internal variable name defined in .OBJ structure. This is
required for every attribute. You need to include the
Internal Object name.
Version
-
When this element or attribute has been introduced.
c) AppInfo for Complex Type Elements.
18
Again this is same as defining AppInfo for simple elements
but the syntax to define these elements is different, since a
complex data type contains multiple elements with in it.
3. Format of AppInfo
As discussed earlier, AppInfo is used to convert the external XML representations
into internal .OBJ elements.
XML Schema has standards constructs for defining types such as Simple types,
Complex types and Elements.
a. Simple Type
Since “Simpletype” is a type definition, we don’t need to capture “App
Info” . Please note that we need to capture “appInfo” where we use this
type to define an attribute.
b. Complex Type
- If Complex Type is not inherited from ExosBase means it
is a DataType and is used for defining containment objects.
So non ExosBase Complex Types can be mapped to
different internal objects based on the containment. So we
can provide map information for non ExosBase Complex
Types.
- If Complex Type is derived from ExosBase means there
should be an internal object which identifies this object. We
need to define AppInfo for this Data type.
ExosBase Complex Data Type App Info:
<xsd:complexType name="PortConfig">
<xsd:annotation>
<xsd:documentation>
Port configuration. This object is used to query or modify port
configuration on the switch.
</xsd:documentation>
<xsd:appinfo>
<version>EXOS 12.0</version>
<internalObject>ports</internalObject>
<module>vlan</module>
</xsd:appinfo>
</xsd:annotation>
--</xsd:complexType>
c. Element
This is used to define the instance of a type. i.e to define an attribute/object.
Element could be of type “Simple” or “Complex”. We need to capture
19
appInfo for every element and there should be mapping to internal
object/attribute.
If the element is “Simple Type”:
<xsd:annotation>
<xsd:documentation>The total number of frames received by the port that occurs
ifframe has a CRC error and does not contain an integral number of octets.
</xsd:documentation>
<xsd:appinfo>
<version>EXOS 11.7</version>
<access>READ</access>
<variable>rxAlign</variable>
<internalObject>intObject</ internalObject >
</xsd:appinfo>
</xsd:annotation>
If element is “Complex Type”:
<xsd:annotation>
<xsd:documentation>This represent the password policy</xsd:documentation>
<xsd:appinfo>
<nameinfo name=" maxAge " variable=" passwd_max_age " object=” acctPasswordSecurity”
version=”EXOS 11.7” access=”READ,WRITE” status=””/>
<nameinfo name=" length " variable=" passwd_min_len " object =” acctPasswordSecurity”
version=”EXOS 11.7” access=”READ,WRITE” />
<nameinfo name=" historyLimit " variable=" passwd_hist_limit " intObject=” acctPasswordSecurity”
version=”EXOS 11.7” access=”READ,WRITE” />
<nameinfo name=" clearLock " variable =" acct_locked_out " object =” acctPasswordSecurity”
version=”EXOS 11.7” access=”READ,WRITE” />
<nameinfo name=" lockOnLoginFailure " variable =" acct_lockout_feature_enabled" object =”
acctPasswordSecurity” version=”EXOS 11.7” access=”READ,WRITE” />
<nameinfo name=" charValidationEnabled " variable =" passwd_char_validation_enabled " object
=” acctPasswordSecurity” version=”EXOS 11.7” access=”READ,WRITE” />
</xsd:annotation>
</xsd:appinfo>
4. All the objects which are being exposed should have following data member at
the end of the definition
<xsd:element name="extension" type="common:ExtensionType" minOccurs="0"/>
<xsd:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded"/>
<xsd:anyAttribute namespace="##any" processContents="lax"/>
<xsd:attribute ref="common:operation"/>
First three elements are needed to support the extensibility (backward compatibility)
and the last one is needed to support sub operation in netconf protocol.
5. Logically related elements should be in a group.
Example:
20
<xsd:complexType name="QoSProfileInfo">
<xsd:sequence>
<xsd:element name="qos" type="QoSProfiles" minOccurs="0"/>
<xsd:element name="minBw" type="Percent" minOccurs="0"/>
<xsd:element name="maxBw" type="Percent" minOccurs="0"/>
<xsd:element name="priority" minOccurs="0" type =”xsd:integer” />
</xsd:sequence>
</xsd:complexType>
6. Functionally related element should be kept in separate schema.
Example:
vlan.xsd , aaa.xsd. port.xsd etc
7. Schema should be structured and modular, and should follow OO principles.
8. Version
We support backward compatibility and forward compatibility please read the section
Forward compatibility:
Client Version
1.0
2.0
3.0
EXOS Version 1.0
Yes
X
X
EXOS Version 2.0
Yes
Yes
X
EXOS Version 3.0
Yes
Yes
Yes
To support backward compatibility, we recommend following rules to be followed while
defining /modifying new or existing schemas:
1. Removal of an element/attribute in the schema is not permitted.
2. Type change of an element/attribute is not permitted.
3. Element’s status can be deprecated and new element can be added.
4. Always add element at the end.
5. Element’s value range can be extended.
9. Namespaces
Always qualify XML Schema and add same default, target Namespaces. Define a new
default namespace qualifier so that if any schema is importing this schema namespace
qualifier will remain the same.
Example:
<xsd:schema xmlns:xsd=”http://www.w3.org/2001/XMLSchema”
xmlns="http://www.extremenetworks.com/XMLSchema/xos/port"
xmlns:port="http://www.extremenetworks.com/XMLSchema/xos/port"
targetNamespace="http://www.extremenetworks.com/XMLSchema/xos/port" version="EXOS
Version">
10. No Schema inclusion in another schema (include) is allowed, use import instead.
21
17. A copy of “.OBJ” structure as xml/text document with the schema so that
developer will have clear understanding what we are mapping.
18. All the schemas should be kept in xsd directory.
12. All the schemas should have copy right notice.
Note: XSD Template: “/code/cfgmgmt/xmld/src/templates/template_schema.xsd”.
4 XML API Implementation
4.1.1 Steps
1. Define the XML Schema and internal mappings for all Object(s) as discussed in
section 3
2. Give a proper name to your schema (typically it is your module name) and place
the schema in your module directory.
3. Define all value mappings in file
“code/cfgmgmt/xmld/src/xsd/valueMapper.xml”, this file contains mapped values
for External Enumerations to internal values.
e.q.:
<valueMapper>
<PortConfig>
<linkState>
<platform type="Default">
<value north="Ready" south="0"/>
<value north="Active" south="1"/>
<value north="NotPresent" south="2"/>
</platform>
</linkState>
---</PortConfig>
--<YourObjectName>
<parameterName>
<platform type=”Default”>
<value north=”EnumName defined in Schema” south=”Backend Process
Value”/>
</platform>
</parameterName>
</ YourObjectName>
</valueMapper>
This file will be used by XMLD module to convert Backend Process internal
values into External Schema enumerations. This is a global file all Enumeration
mappings.
< YourObjectName> - Defined in XML Schema
22
< parameterName> - Name of the attribute defined in XML Schema
<platform>
- “default” if the value is independent of platform, other
wise specify value for each platform.
EnumName
- Name of the enum defined for parameterName in Schema
Backend Process Value - Backend Process returned value for this attribute/enum.
4. Every external XML Object should be mapped to one or more Internal Objects,
i.e it is required to form multiple internal Commands to get data from backend
modules (like CLI). In most of the cases, these commands are generated by
XMLD module (using appInfo defined in XML Schema). XMLD module has a
way to modify the default behavior of index parameter/get/set/delete APIs as
described below.
XMLD framework has default implementation for constructing commands,
sending commands to backend and constructing the response. But, in some cases
you might to override the default behavior provided by XMLD module. You
could this by registering your callbacks with XMLD. You can add special handler
code inside those callbacks.
We might need to add any of following callbacks based on functionality and your
backend APIs implementation.
.
a) Index Mapper
This function will be used to modify index parameters or to
add some additional information before sending the
command to the backend (Similar to CLI).
By default XMLD module pushes
“<rowStatus>create</rowStatus>” for CREATE operation,
“<rowStatus>delete</rowStatus>” for DELETE operation
and “<rowStatus>configure</rowStatus>” for SET
operation to the backend as part index parameter
construction and if backend is expecting something else
you need to override this behavior by using
“IndexMapperCalleback”.
b) Get Call back
You can modify the default “get” functionality provided by
XMLD module, this is required in some cases to get
specific parameters/or to modify the backend get
commands or to construct External XML data.
c) Set Callback
You can modify the default “set” functionality provided by
XMLD module, this is required in some cases to set
additional/ or to modify parameter names.
23
d) Create Callback
You can modify the default “create” functionality provided
by XMLD module, this is required in some cases to set
additional/ or to modify parameter names.
e) Create Delete
You can modify the default “delete” functionality provided
by XMLD module, this is required in some cases to set
additional/ or to modify parameter names.
If you decide to add callbacks then you need to add a file called “module_xmlmapper.c”
(e.q: “code/l2protocol/vlan/src/valn_xmlmapper.c”) in your module directory.
You must add a function called “xmlApi<Module>Init ( )” in that file. You can set all
callbacks inside this function. This function must be registered to XMLD module. To do
that, you need to add this function call in the file
“code/cfgmgtm/xmld/src/xml_api_register_callback.c” [function:
xmlApiRegisterCallbacks() ].
Please include necessary header files, otherwise you get compilation errors. Please note
that this file should be linked to XMLD process, i.e. you must need to add the same file
name in “xmld” Makefile.
5. Make Process
1. Make a soft link to your xsd file in “xmld/src/xsd/”
2. add XSD file name in “xmld/src/xsd/xsdlist.lst”
3. add namespace (generally it is <moduleName>) which is defined in
your XSD file to “xmld/src/xos.dat” file
4. add namespace (generally it is <moduleName>) which is defined in
your XSD file to “xmld/src/switch.wsdl” file
5. include <module>_xmlmapper.h (If you have one) in
/xmld/src/makefile
6. “make fwkcode” in xmld/src
7. make
4.1.2 Issues you might phase
1) “make fwkcode” will get failed if schema has syntax errors. This means Parsing is
failed.
Please make sure schema does not have any syntax errors. Firefox browser will
show you syntax errors including line numbers (just open it from Firefox
browser).
2)
Missing data types (data types are used but not defined any where, or not
associated name space properly for that data type)
24
“make fwkcode” will show you error message.
3) Make fwkcode will generate two files “xmlapi_gen_objinfo[.hc]”, please make
sure there are entries for your schema elements in that file.
4) If you don’t specify your xsd file in xmld/src/xsdlist.lst, xsd will not be linked to
xmld process. Please make sure, your xsd has an entry in “xmld/src/xsd/xsdlist.lst.
5) If you don’t add name space in xos.dat and switch.wsdl, XMLD module can not
generate stubs for your Schema.
6) Please make sure your xsd have following entries for your ExosBase Complex
data types (i.e externally exposed APIs)
<xsd:complexType name="AccessObject">
<xsd:annotation>
<xsd:documentation>
(Internal Use)
</xsd:documentation>
</xsd:annotation>
<xsd:choice>
<xsd:element name="portErrorStats" type="port:PortErrorStats"/>
<xsd:element name="portConfig" type="port:PortConfig"/>
<xsd:element name="portUtilizationStats" type="port:PortUtilizationStats"/>
<xsd:element name="portQoSStats" type="port:PortQoSStats"/>
<xsd:element name="portTrafficStats" type="port:PortTrafficStats"/>
<xsd:element name="loadSharing" type="port:LoadSharing"/>
</xsd:choice>
</xsd:complexType>
<xsd:complexType name="objectList">
<xsd:annotation>
<xsd:documentation>
(Internal Use)
</xsd:documentation>
</xsd:annotation>
<xsd:sequence>
<xsd:element name="moduleObject" type="AccessObject" minOccurs="0"
maxOccurs="unbounded"/>
</xsd:sequence>
</xsd:complexType>
XMLD framework considers objects only those defined inside “AccessObject”. If
you don’t have an entry in “AccessObject”, XMLD can not consider that Object as
API Object.
7) By default XMLD module pushes “<rowStatus>create</rowStatus>” for
CREATE operation, “<rowStatus>delete</rowStatus>” for DELETE operation
and “<rowStatus>configure</rowStatus>” for SET operation to the backend as
part index parameter construction and if backend is expecting something else you
need to override this behavior by using “IndexMapperCalleback”. In you don’t
have an attribute “rowStatus” in .obj and if you don’t modify index parameters
values you will get an error from backend module (possible error: ”no
25
configuration action is supported”). Please check the existing implementation:
l2/protocol/vlan/src/vlan_xmlmapper.c – xmlApiVlanIndexMapperCb();
4.2
Interoperability
All the XML schema and WSDL files should support following packages
1. gSoap
2. Java Axis
3. soapUI
4. perl soapLite
5. Flex Web Services
6. Microsoft Web Services Framework
7. C#, .NET
All the APIs which follows design principles described earlier will support the above
packages. Developer need not worry about this.
4.3
EXOS Reference Implementations, XML Schema/WSDL files
1.
WSDL files
exos/code/cfgmgmt/xmld/src/switch.wsdl
2.
Schema Files
Vlan : exos/code/l2protocol/src/vlan.xsd.
Port: exos/code/l2protocol/src/port.xsd.
AAA: exos/code/cfgmgmt/aaa/src/aaa.xsd.
3.
Get/Set/Create/Delete API implementations.
Vlan : exos/code/l2protocol/src/vlan_xmlmapper.c
Port: exos/code/l2protocol/src/vlan_xmlmapper.c.
AAA: exos/code/cfgmgmt/aaa/src/aaa_xmlmapper.c.
4.
Value Mappings
exos/code/cfgmgmt/xmld/src/xsd/valueMapper.xml
5.
Templates
exos/code/cfgmgmt/xmld/src/templates/
5 XML Testing
5.1 Unit Testing
1. A CLI based XML Client tool is available for you your API testing
Running Test Tool
26
-
Telnet to switch
At CLI prompt, enable web http (this is to enable web
access)
go to source “xmld/src/test”
./xmlHttpClient <switch-ip>
Type help
2. Perl Scripts are available in “exos/tools/xmlSDK/api/code/perl” , you can
add a new perl script for your module in that directory.
Example perl scripts are available in that directory with names “getOne.pl”,
“getAll.pl”, “getNext.pl”, “setOne.pl” and “deleteOne.pl”. You can make
copies of these files and edit them to include your object/parameter names. It
is encouraged to add working Perl examples for your APIs in this directory.
3. You can also try testing your APIs using CLI
XML requests will be generated when you make xmld/src directory.
Following will get generated.
switchBinding.get.req.xml
switchBinding.set.req.xml
switchBinding.create.req.xml
switchBinding.delete.req.xml
You require editing these xml requests to include your Object Names.
-
Open Console or Telnet session with switch
At CLI prompt, enable xml-mode
Paste the XML Request (the one created/modified above).
Please note that, enable xml-mode does not require “sessionId”, i.e you don’t
need to enter any header information in the above XML Requests. You have
to specify Object Name and parameter(s)/Parameter values only.
4. Try to download SOAPUI from Internet and install it on your desktop.
You can generate and send XML requests using this tool. Please read the
documentation provided with the tool.
5.2 Integration Testing
-TBD-
6 Process
27
6.1
Set Up
Any new schema development or modifications of existing schemas have to follow the
steps outlined in section 3.2 and section 4.
The list of steps that need to be taken to get the XML development process in place is
outlined in following section. Whenever work is started on any schema/WSDL
implementation (proprietary or standard):
1. A note has to be sent to the Review mailing list outlining the intent that a new
schema/WSDL is being planned and the description of the planned
schema/WSDL. EPI Center team could work with the embedded software team to
design the schema/WSDL.
2. Before you start writing schema/WSDL, read the section 3 and follows.
3. Once the schema/wsdl is designed, a note has to be sent to Review with the newly
designed schema/WSDL, mapping info xsl sheet, “.obj” in the text/xml format.
4. Implementation can then start. The reason we want to allow implementation to
start is to support small changes to the schema/wsdl without having to wait for the
approval process to complete.
5. Each of the development teams (EXOS/ EPICenter) is given a period of about 1
week to respond to the schema/WSDL with their comments. This includes testing
the schema within their tools etc
6. We can call a meeting to finalize on the schema/WSDL. After the meeting, no
changes to the schema should be made by the developer.
7. After the meeting, we check in the new schema/WSDL into the EXOS source
tree.
6.2
XML Review guidelines
FS document should contain the Use Cases, modeling of API Objects as described in
section 3.2.2 and this should reviewed as part of FS Document review. Once FS review is
over, XML Schema along with modeling should be sent for review to the email alias
“EXOS XML-Review”. This should be done before the start of API Implementation.
Following gives some overview what needs to be reviewed.
External/Internal XML API review Teams:
1. Design of API Objects
2. Naming of Attributes/Parameters, Naming of ENUM values.
3. Reusability of Data types (please check , are there redundant data types
introduced)?
4. Object hierarchy, use of inheritance/containment relationships in object
modeling?
5. Redundant information/parameters
6. Parameter description, version, access rights, internal mappings.
28
Internal Review Team:
External Object
– External object we are exposing this object.
Example: TACACSConfig
Internal Object(s) -- Which internal Objects we are going to use to implement this
external Object.
Example: TACACSConfig is going to mapped tacacs_service, tacacs CLI objects
External or ExternalName -- external element name. This is an element of external
Object.
Example: authServerEnabled is an external element and being mapped to enable data
member of tacacs_service data member.
Internal or InternalName -- internal data member name. This is a data member of
internal object.
Example:
authServerEnabled is an external element and being mapped to enable data member of
tacacs_service data member.
Access
-- This tells what is the access right of this element name.
Example: authServerEnabled is READ, WRITE
Version
-- This is the version when we introduce external element.
Example: This has been introduce in EXOS 11.7
module
-- This is the process name which supports this object.
Example: This has been introduce in EXOS 11.7
Documentation of externalName – This is the documentation of external element.
So what the developer has to review:
1. Mapping of the external Object to internal Object:
Mapping from external to internal object mapping and internal object.
Access right. If external object is exposing READ, WRITE then the internal
object should support those rights.
29
2. element’s externalName to datamember’s internalName and their access
right:
Access right (READ, WRITE, CREATE, DELETE etc) of external objects should
be supported by internal object being mapped
3. Acess right:
This can have READ, WRITE, CREATE, 11.X(Not Supported), DELETE, ADD,
REMOVE.
4. Version:
Does this internal data member is supported in the specified EXOS version?
5. Module:
Does this module support the internal object?
6. Documentation:
Is provided documentation correct and sufficient?
6.3
Release Sign Off
When a particular embedded software version is being released:
2. Everyone in the Extreme-XML-Review has to sign off on the implemented
Schema/WSDL. Only when everyone has signed off, do we allow the product to
be shipped.
3. The EPI Center team makes sure that the latest xml agent works with EPICenter
4. The EPI Center and SQA teams will run some XML automation tool to test out if
the Schemas/WSDLs implemented conform to the one in our repository.
5. The XML process owner will copy all the schemas and WSDLs to the global
location.
6. List of Outstanding Tasks
7 Appendix
7.1 References
External References
Tutorial on XML Schema: http://www.w3schools.com/Schema/default.asp
Tutorial on WSDL: http://www.w3schools.com/WSDL/default.asp
XML Schema Reference Guide: http://www.w3.org/XML/Schema
WSDL Reference Guide: http://www.w3.org/TR/wsdl
30
EXOS Wiki for XML Infrastructure
http://exos-wiki/exos_wiki/index.php/XML_API
7.2 FAQ
7.2.1 General
1. Why do I need to read this document?
This document describes process, design, implementation, testing and
maintenance of XML API development for EXOS features. This is a kind of
handbook for an XML API developer.
2. Why do I develop XML APIs for my module?
Extreme strategy is to provide open interfaces for all EXOS features. XML APIs
provides the ease of developing configure/monitor applications outside the box.
3. What is XML Schema?
Please refer section 3.1.
4. What is WSDL?
Please refer section 3.1.
5. How can I find if there are any syntax errors in XML Schema?
Lots of tools available in the internet. Firefox browser can show you the syntax errors
with line number when you try to open the file with it.
6. What are the steps involved in designing XML APIs?
Please refer section 2
7. Whom should I sent Schema/WSDL documents for review?
Refer section 6.2
8. Is there any reference XML API developed in EXOS?
Refer section 7.1
9. Is there any reference XML Schema or template?
31
Refer section 3.2.2
10. What is XML SDK?
Software development kit for developing Client Application Programs. Client
Apps are run in external machines and they can talk to EXOS using XML APIs.
SDK has XML Schemas, WSDL files and client Examples using Java/Perl. This
SDK will be given to the Customers who wants to develop configure/monitor
applications.
7.2.2 Implementation
11. Do I need to change backend code to support XML APIs for CLI commands that I
already have?
May or may not, depending on the .OBJ interfaces that you have. Sometimes you
might need to write/modify .objs. Please note that in that scenario, you will end
up adding code in mapper callbacks (section 4.1.1) for command
construction/data construction if you don’t modify backend .obj interfaces
12. What are the kinds of APIs supported by XMLD framework?
Refer section 3.1
13. What is Get API/Get Next API? What are the filtering options in Get API?
Operation used to get data for objects from the switch. The type of
object and other options for the get operation are specified as part
of the getRequest message. This operation can be used to get either a specific
object or a set of objects of a type. The data returned by this operation is
contained in the getResponse message.
Get Next uses same prototype as Get API with some additional parameters
“action=next” and “maxSize=<num>”.
Application can also pass attribute values in ‘getRequest’ API call for retrieving
only those objects which satisfies the attribute(s) condition.
14. Describe Set/Delete/Create API?
Set API: Operation used to set data for an object on the switch. The type of
object and values to set is specified as part of the setRequest message.
Create API: Operation used to create an object on the switch. The type of objects
and its values are specified as part of the createRequest message.
32
Delete API: Operation used to delete an object from the switch. The object to
delete is specified as part of the deleteRequest message.
Please note that not all objects required supporting get/set/create/delete
operations. You would need to associate Objects and Operations at design time.
15. Describe XML API error handling capabilities?
a) Backend error : XML API returns SOAP-Fault with
the backend returned error message for any API
call. XMLD does not modify the backend returned
error message.
Incase backend does not return any objects for Get
API call, no error message will be returned to the
client and also response does not contain any
objects (i.e empty response will returned to client).
b) API request error: If XMLD has failed to
understand the packet or failed to authenticate the
client, appropriate error message will be returned.
16. What is DOM programming, why do I need to understand DOM?
The DOM is a programming interface for XML or HTML documents. It defines
the way a document can be accessed and manipulated.
Using a DOM, a programmer can create a document, navigate its structure, and
add, modify, or delete its elements.
EXOS XML API framework has its own DOM Library for parsing, traversing
and constructing XML Data. Developer needs to understand DOM API
interfaces for parsing the backend returned XML data, and to send XML
commands to the backend module. If you don’t need to write callbacks, probably
you don’t need to understand DOM APIs for your implementation.
17. What DOM APIs in C available for API development? Can you point me the file
where I can find Dom APIs in xmld/src?
xmld/src/xmldom_api[.hc]
18. Why do I need to register callbacks for API implementation?
Refer section 4.1.1 [4]
19. What are the typical errors I get while implementation?
a) Compile Time Errors
33
•
•
•
Namespace which is defined in your xsd is missing or not
consistent in any of following files
switch.wsdl
<your_module>.xsd
xos.dat file.
-
Syntax Errors in XSD file
Data types used but not defined
Redefinition of same data type across XSDs.
b) Runtime Errors
-
Back end mappings are not proper,
Please check the backend commands that you are receiving
when XML API requests are invoked.
“debug ems clear trace <module> all all”
“debug ems show trace <module> all all”
-
If backend module receives a command with invalid
attribute/object, you might need to modify the schema or
you might need to override the behavior using callbacks
and you might need to introduce new backend .OBJ
variables/objects.
You might have missed adding Enum Mappings in
valueMapper.xml file
Callbacks may not be implemented properly.
If you don’t the callbacks getting executed, you might have
forgotten to register callbacks with XMLD.
xml_api_register_callback.c
20. How the conversion will happen from XML API requests to backend _t_get and
_t_set function calls?
XML API requests are converted into series of backend _t_set/_t_get function
calls. This is similar to what we have for CLI.
21. How do I build XML API response from the data returned by backend modules?
XMLD framework tries to build the response automatically with in its limitations,
and if the behavior is different from what XMLD supports then you need to build
the response from backend data inside Get/Create/Delete/Set callbacks.
22. What do you mean by north-bound and south-bound values, how do I convert
values?
34
North-bound values are what XML API client will see in the response, and southbound values are what back end modules will get/return. Sometimes we need to
map south bound values to north bound values.
XMLD tries to convert south bound values to north bound values in following
cases:
-
Enum Mapping (using static valueMapper.xml file).
string to octet Conversion (Vice versa)
int to netmask (Vice versa)
string to password
octet to tcpAddress
For ENUM mappings, you need to define enumeration values in valueMapper.xml
file and for remaining data mappings (listed above) you would need to specify them
in xsd file using “typeMap” app Info parameter as described below.
You would need to have following appInfo in the XSD for non ENUM conversation:
<typeMap extType="string" intType="octet"/>
<typeMap extType="octet" intType="string"/>
<typeMap extType="tcpAddress" intType="octet"/>
<typeMap extType="int" intType="netmask"/>
<typeMap extType="netmask" intType="int"/>
Example:
<xsd:element name="vacmViewTreeFamilyViewName" type="common:StringLen256">
<xsd:annotation>
<xsd:documentation>View name.</xsd:documentation>
<xsd:appinfo>
<variable>vacmViewTreeFamilyViewName</variable>
<typeMap extType="string" intType="octet"/>
</xsd:appinfo>
</xsd:annotation>
</xsd:element>
Conversion logics are implemented in xmlapi_utils.c/stringLib.c.
If you need any new value mappings, please send your requests to Infrastructure
team.
23. Can I change schema parameters/value mappings in the box with out rebuilding
the image?
Yes, you can. valueMapper.xml file is located in the switch /exos/config/www/api/xsd/. Edit the file and restart the xmld process.
35
24. Can you point me the location of Schema/WSDL files in EXOS file system?
Directory Path for WSDL/Schema files in EXOS box.
WSDL : /exos/config/www/api
XSD : /exos/config/www/api/xsd
Root path for HTTP public access is configured as “/exos/config/www”
URL path for WSDL files:
switch.wsdl : http://<ip-address>/api/switch.wsdl
xos.wsdl : http://<ip-address>/api/switch.wsdl
e.q: http://10.203.1.6/api/switch.wsdl
URL path for XSD Files:
port.xsd : http://<ip-address>/api/xsd/port.xsd
vlan.xsd : http://<ip-address>/api/xsd/vlan.xsd
e.q: http://10.203.1.6/api/xsd/port.xsd
7.2.3 Debug, Test and Examples
25. How do I debug my XML API?
Please refer section 5.1
26. Are there any utilities for debugging XML API Utilities?
You can get the API request/response traces. CLI commands for XMLD trace
configuration:
“debug xmld show trace-info”,
“debug xmld clear trace-info”,
You can get backend call traces using CLI commands:
“debug ems clear trace [<module> | all] [match | all]”
“debug ems show trace [<module> | all] [match | all]”.
Please talk to EXOS Infrastructure team for additional support.
27. How do I test my APIs?
Please refer section 5.1
28. How do I get sample stub XML requests for APIs?
36
Make xmld directory will generate xml API requests. Please refer 5.1 for details.
29. What are XML API Perl examples, where is the location of those Perl examples?
XML API sample perl client programs for invoking XML API calls. These
sample programs describe use cases of how a client can invoke API calls. These
client programs are developed using Perl SOAP-Lite library.
Perl Samples Directory Path: exos/tools/xmlSDK/api/code/perl
30. Do I need to write Perl example(s) for my API?
We encourage you to write Perl Examples for your module which demonstrates
API capabilities/use cases. Customer can use these samples for writing their
Applications.
7.2.4 Miscellaneous
31. What is session management in XMLD? What is the maximum number of
sessions supported in XMLD?
XMLD maintains max 6 sessions with its external clients. Client will
initiate/terminate a session with EXOS using OpenSession/CloseSession request,
XMLD responds with a session Id (if number of number sessions are less than 6) and
after that Client has to send Session Id in every XML API request. There is a CLI
command for viewing number of sessions: “show session all” and admin can clear
session(s) using “clear session [<session-id> | all]”.
32. Whom should I contact if I face problems with XML API implementation?
EXOS Infrastructure Team.
37