# Getting Started

# Introduction

The fundamental task of Akixi Web Services is exchanging data between the Akixi Application and other systems. Akixi Web Services API uses a standardized XML messaging system in order to receive data from client applications and send responses. Messaging system used by Akixi Web Services is described by a Web Service Definition Language (WSDL). Software applications written in various programming languages and running on various platforms can use Web Services to invoke Akixi operations in a transparent and straightforward way.

Akixi Web Services can be used to programmatically access administrative features of the Akixi Application. For example, you can use Web Services to create, list, change and remove Telephony Servers, Partitions, Devices, Application Users and other Akixi configurational elements & components.

Corresponding operations can be automatically invoked from your client-side logic by building requests and handling server-side responses.

To call a Web Service on a remote server, you need to correctly define required parameters and then invoke a request on a certain endpoint via Web Services client. A response can then be processed (i.e. by parsing its content).

A detailed overview of currently supported endpoints, parameters and responses is provided later on within this chapter.

# Terminology & Value References

# Text Value References

This documentation will often provide specific examples of literal text values as well as discuss their usage for XML element content values, XML attribute values, and other programming-language specific functional arguments or return results. In almost all cases, text values will always be shown delimited with double-quotation characters, where the quotation characters are not part of the actual underlying value, e.g. “The cat sat on the mat.” actually denotes an encoded UTF-8 octet sequence of:

0x54,0x68,0x65,0x20,0x63,0x61,0x74,0x20,0x73,0x61,0x74,0x20,0x6F,0x6E,0x20,0x74,0x68, 0x65,0x20,0x6D,0x61,0x74,0x2E

Where the text value actually needs to include double quotation values, these will either be specified using an appropriate scheme clearly documented with that particular text value. Alternatively, the Java backslash escaping style will be used in all other cases, e.g. “The cat said \“I am a cat\”.”, which denotes the UTF-8 byte encoding:

0x54,0x68,0x65,0x20,0x63,0x61,0x74,0x20,0x73,0x61,0x69,0x64,0x20,0x22,0x49,0x20,0x61, 0x6D,0x20,0x61,0x20,0x63,0x61,0x74,0x22,0x2E

Refer to section 3.10.6 ("Escape Sequences for Character and String Literals") of the Java Language Specification to learn more about the Java String literal escaping scheme.

Similarly, single character values will be shown delimited with single quotation characters and the same escaping scheme if required, e.g. ‘x’ for UTF-8 octet encoding 0x78, and ‘\’’ or ‘\u0027’ for `0x27 (the single quotation character itself).

Note that the actual byte encoding of text values may or may not be UTF-8 as appropriately required in the context of the given example (i.e. in Java code file & SOAP XML examples, literal text values will almost always be encoded as UTF-8, whereas in-memory at runtime the Java String class stores text as an array of 16-bit Unicode character values using surrogate-pair encoding for extended multi-plane Unicode characters).

Text or character values should ordinarily be assumed to be case-sensitive, where the precise character case construction shown, should be exactly replicated when given as an input value to an API request or sample code routine.

Unless otherwise stated, literal text values should be assumed to be the same regardless of the language/locale associated with a Web Services API session.

# BroadWorks Component Terminology

For Cisco BroadWorks telephony platform integrators & developers, this documentation stipulates rules for mapping certain BroadWorks concepts to Akixi Service configuration entries.

Unless otherwise specified, the terms BroadWorks “Enterprise” and BroadWorks “Service Provider” (“SP”) can be used interchangeably. Similarly, the terms “Enterprise Group” and “SP Group” and “Service Provider Group” can also be considered the same for the purposes for any cross-system mapping interpretation rule(s) given.

# Akixi Web Services Endpoints

You must correctly provide an endpoint in order to invoke a Web Service request. Akixi Web Services API currently supports one endpoint which is as follows:

servicename.akixi.com/CCS/WS

The above URL can be used over the protocols HTTP or HTTPS (whichever is supported, though HTTPS is strongly recommended). Replace the text highlighted in red with your Akixi Application’s domain/server name.

# XML Schema

The Web Services XML Schema can be downloaded using the appropriate URL for your Akixi Service. An example URL is provided below (replace the text highlighted in red with your Akixi Application’s domain/server name). Viewing the schema file can help Developers learn more about Akixi Web Service’s API data structures such as elements, containers and other supported types.

servicename.akixi.com/CCS/WS?wsdl

# Web Services Request/Response

This chapter also provides some details related to general requests and responses made over Akixi Web Services.

In order to fully understand this chapter, the reader must be familiar with general Web Services concepts and fully understand the structure of a typical SOAP request/response.

If you would like to learn more about the Akixi Service or about its provisioning concepts & application components used by the Akixi WS API, please refer to the “Useful Links & Resources” chapter. Specifically the Office Administration Training Notes documents are the recommended areas to start with first for hosted telephony platform Aggregators or Resellers - choose the appropriate document based on your telephony platform manufacturer type.

# SOAP Envelope

The SOAP envelope defines the start and the end of the message so that the receiver knows when an entire message has been received. The SOAP envelope solves the problem of knowing when you are done receiving a message and are ready to process it. The SOAP envelope is therefore basically a packaging mechanism.

Please note that:

• Every SOAP message has a root Envelope element.
• The Envelope element is a mandatory part of a SOAP message.
• Every Envelope element must contain exactly one Body element.
• Currently a SOAP 1.1 compliant envelope is used & expected by the Akixi Service. Therefore the namespace for the SOAP elements which is at the time of writing this documentation is http://schemas.xmlsoap.org/soap/envelope/ must be used.

# SOAP Request Body

The SOAP body is a mandatory element that contains the application-defined XML data being exchanged in the SOAP message. The body must be contained within the envelope and must follow any headers that might be defined for the message.

The body is defined as a child element of the envelope, and the semantics for the body are defined in the associated SOAP schema.

# Request Structure

A SOAP request can be described as an XML data structure that is sent to a Web Service in order to invoke a certain operation.

Typical Akixi SOAP request has the following structure:

The Envelope and Body elements are the essential parts of the SOAP Protocol and would be familiar to anyone who had prior SOAP experience.

The Request element includes actual operation-related information (e.g. operation name, request parameters and child elements like OperationPayload). The namespace of the elements must be identified from the WSDL schema which may change over the subsequent versions of Akixi Web Services API.

The SOAP Request element content is described in the next sub-section.

# SOAP Request Elements

In Akixi Web Services API, the request definition can be found on the root level of the SOAP Body.

Akixi Web Services requests (will be referred to as “requests” interchangeably hereafter) have mandatory and optional parameters. These parameters may vary from one request to another. However, every request must certainly include:

• A value for InvokeID parameter to track request results received via a subsequent response.
• A value for SessionID parameter to identify the Akixi administrative User (the only exception is the CreateSession request, because the SessionID value does not actually exist before its invocation).

Most requests will also include operation-specific OperationPayload element contents, which will be Property tags as well as Container XML sub-elements.

# SOAP Request Example

The request shown below can be used to obtain the configuration parameters of an existing Akixi Telephony Server entry (also known as a Telephone System entry):

<!-- Envelope starts here. -->
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns="http://www.akixi.com/2016/03/CCS/WS?xsd">
    <!-- Request body starts here. -->
    <soapenv:Body>
        <!-- Request definition starts here. -->
        <Request Operation="TelSysInfo">
            <!--Version value is optional, but if not mentioned then previous version will be used.-->
            <Version>v2</Version>
            <!-- InvokeID value is mandatory. -->
            <InvokeID>0010</InvokeID>
            <!-- SessionID value is mandatory for all requests except CreateSession. -->
            <SessionID>EFA4902A7F61D03E42BF3222B0A246BF</SessionID>
            <!-- OperationPayload includes operation-specific data. -->
            <OperationPayload>
                <!-- Specify a TelSysID to obtain all related values. -->
                <Property Name="TelSysID">3</Property>
                <!-- Set this Boolean value to True to display advanced fields. -->
                <Property Name="AdvancedFields">True</Property>
            </OperationPayload>
            <!-- Request definition ends here. -->
        </Request>
        <!-- Request body ends here. -->
    </soapenv:Body>
    <!-- Envelope ends here. -->
</soapenv:Envelope>

This request includes some commonly used concepts of the Akixi Web Services API:

• Envelope*
• Body*
• Request*
• Version
• InvokeID*
• SessionID
• OperationPayload

Elements marked by asterisk (*) must be provided within every Akixi Web Services Request. SessionID parameter is mandatory for all requests except CreateSession. OperationPayload parameter is not always required, but commonly used within essential requests. The Version parameter is optional, but should be provided to access the right and latest version of APIs, if not mentioned then the previous version of APIs will be executed. To know the right values of Version parameter, refer to the SOAP wsdl file, sample values of Version parameter are v1 and v2.

# Response Structure

A SOAP response can be described as an XML data structure that is returned by a Web Service once the response is processed.

Typical Akixi Web Services SOAP response has the following structure:

The Envelope and Body elements are the essential parts of the SOAP Protocol and would be familiar to anyone who has prior SOAP experience.

The Response element also contains a Result attribute, which depicts whether the corresponding request was successful. Some operations also return server-side configuration information within further child elements.

SOAP response elements are described in the next subchapter.

# Result Attribute

Once the request is processed, the Akixi Web Services API returns a response that includes the operation result within an XML data structure that conforms to the WSDL file’s schema.

A client-side application would ordinarily read the Akixi Web Services response result in order to check whether the operation was successful.

The list of possible response results returned by Akixi Web Services is provided in the table below:

# SOAP Response Examples

# Success Scenario

Success scenario responses may vary from one operation to another. Every response always includes the response’s Result attribute value (e.g. Success) and the InvokeID child element:

<!-- Parse the Response element’s Result attribute value in order to check whether --> 
<!-- your operation was successful. -->
<Response Result="Success">
    <InvokeID>00001</InvokeID>
</Response>

Some responses may return Property values:

<!-- Parse the Response Result value to check whether the operation was successful -->
<Response Result="Success">
    <InvokeID>00002</InvokeID>
    <!-- If the operation was successful, parse the Success element’s Property child --> 
    <!-- element to obtain response values. -->
    <Success>
        <Property Name="SessionID">EFA4902A7F61D03E42BF3222B0A246BF</Property>
        <Property Name="Nonce">a8aa7a7ea26f9225d1b03ea7e8e6a6ca</Property>
    </Success>
</Response>

Property values can be also be returned within containers:

<!-- Parse the Response Result value in order to check whether an operation was successful -->
<Response Result="Success">
    <InvokeID>00003</InvokeID>
    <!-- If operation was successful, parse the Success element’s Container child elements -->
    <!-- in order to obtain response values. -->
    <Success>
        <Container>
            <Property Name="TelSysID">1001</Property>
            <Property Name="Description">Telephony Server 1001</Property>
            <Property Name="TelSysType">BroadSoft Broadworks</Property>
            <Property Name="CommsStatus">Running</Property>
            <!-- Etc... -->
        </Container>
        <Container>
            <Property Name="TelSysID">1002</Property>
            <Property Name="Description">Telephony Server 1002</Property>
            <Property Name="TelSysType">BroadSoft Broadworks</Property>
            <Property Name="CommsStatus">Out-Of-Service</Property>
            <!-- Etc... -->
        </Container>
    </Success>
</Response>

# Failure Scenario

If the requested operation was unsuccessful (i.e. if the result type depicts Fail), you will need to read further details relating to the failure. A response example for an unsuccessful request/operation is provided below:

<!-- Parse the Response element’s Result attribute value in order to check whether -->
<!-- your operation was successful. -->
<Response Result="Fail">
   <!-- If the operation was unsuccessful, you should read the error-related details and -->
   <!-- handle the error accordingly -->
   <Error>
       <ErrorCode>10101</ErrorCode>
       <ErrorMessage>Invoke ID is not specified within the request.</ErrorMessage>
   </Error>
</Response>

You will find the full list of error codes and descriptions within the “Error Codes” chapter.

The next two chapters describe all currently supported authentication-related and administrative requests, responses, error codes and other essential Akixi Web Services-related details.