ExtremeXOS XML API Developers Guide
Transcription
ExtremeXOS XML API Developers Guide
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