API User Guide for the Cisco TelePresence Exchange System Release 1.0
Overview
Downloads: This chapterpdf (PDF - 86.0KB) The complete bookPDF (PDF - 614.0KB) | Feedback

Overview

Table Of Contents

Overview

API Overview

Development Guidelines

About Web Services

About the API Architecture

Security

API Versions

Required Parameters

Error Handling

Queries


Overview


Revised July 12, 2012

The Cisco TelePresence Exchange System is an integrated video service-creation platform that enables service providers and strategic partners to offer secure cloud-based managed and hosted Cisco TelePresence and business video services. The Cisco TelePresence Exchange System is a software environment that simplifies end-to-end subscriber service provisioning; optimizes intelligent call routing for endpoints and network bandwidth; manages the call processing and allocation of media resources for conferencing; consolidates a centralized control point for management, billing, and administration; and presents an open application programming interface (API) for application integration such as scheduling and directory services.

As part of the Cisco TelePresence Exchange solution, the Cisco TelePresence Exchange System exposes a set of standards-based APIs to provide integration across business and operational support systems. Based on proven technology and powered by a fully redundant and horizontally scalable architecture, it delivers an open, scalable, and robust multi-tenant solution that can grow in scale and functions based on service needs.

This chapter provides a general description of the APIs and includes the following sections:

API Overview

Development Guidelines

About Web Services

About the API Architecture

Security

API Versions

Required Parameters

Error Handling

Queries

API Overview

The Cisco TelePresence Exchange System provides the following APIs:

Scheduling

The Scheduling API provides web services to control scheduling of services such as Meet-Me and two-party scheduled meetings on the Cisco TelePresence Exchange System.

By using the Scheduling API, you can schedule, modify, or cancel meetings and retrieve information about organizations and rooms.

Call Detail Record (CDR)

The CDR API provides web services to retrieve and manage call detail records for services provided by the Cisco TelePresence Exchange System.

For more information about the APIs, see the Cisco TelePresence Exchange page on the Cisco Developer Network at http://developer.cisco.com/web/ctx/home.

The Cisco TelePresence Exchange System software image includes all components that are required to use the APIs. The APIs require no additional software download or installation.

Development Guidelines

Cisco recommends the following practices to reduce the number and extent of any updates that may be necessary to support compatibility with a later release of Cisco TelePresence Exchange System:

New interface events, methods, responses, headers, parameters, attributes, elements, or new values of existing elements, will most likely be introduced in new versions of the APIs. Each new version of the API includes a separate Web Services Description Language (WSDL). When developers upgrade to the new API version, they may need to provide additional generic or null parameters to existing service methods or call additional methods to achieve the same result.

Previous interface events, methods, responses, headers, parameters, attributes, and other elements will remain defined in the API, and will appear in the API in the form of separate WSDLs for each supported release.

Applications must not be dependent on interface behavior that is the result of defects (behavior not consistent with published interface specifications) because the behavior can change when the defect is fixed.

Cisco recommends that developers have a strategy for migration to newer Cisco TelePresence Exchange System API versions. Developers must note cases in which Cisco removes items such as methods, parameters, responses, and attributes in newer API versions, and ensure that they remove these from their application as soon as possible.

About Web Services

The web services standards define a framework for clients to request services over a network by using XML-based messaging. Web services operations use an XML-based protocol such as Simple Object Access Protocol (SOAP), which defines the envelope structure, encoding rules, and conventions for representing web service requests and responses. These requests and responses are transmitted as XML-based SOAP messages over HTTP.

Although SOAP messages can be complex, a web services framework hides the complexity from the client developer. A client creates a proxy (a local object that represents the service) and then invokes methods on the proxy. The web services framework converts the API method calls and responses to and from SOAP messages. Cisco recommends that developers use powerful web services frameworks such as Axis for Java developers to simplify development and avoid direct XML document manipulation.

About the API Architecture

You access the Cisco TelePresence Exchange System APIs by using a standards-based web services infrastructure that is implemented on the administration server.

API Clients can run on different OS platforms and communicate with the administration server by using SOAP-based web services. SOAP provides an XML-based communication protocol and encoding format for inter-application communication. The Cisco TelePresence Exchange System API uses document-style web service operations.

The API conforms to the SOAP Specification 1.1 and the WSDL Specification 1.1.

The SOAP messages (between client and server) are transported over HTTP to a unique URL that is associated with each of the APIs.

The web services provided by the API are specified by a set of WSDL files. Each web service is defined as a request-response operation (each request results in a correlated response message from the Cisco TelePresence Exchange System). The response message contains information that is relevant to the requested action or data query.

Each request (and the associated response) is a complete transaction. There is no requirement for session or state information to be maintained on the server between requests from a given client.

Security

The current API uses HTTP basic access authentication. API clients must include authentication credentials with each API request. The mechanism is HTTP basic access authentication, using Base64 encoding of username and password.

API Versions

The Cisco implementation of Cisco TelePresence Exchange System APIs may change over time in response to the evolving needs of our partner community.

The APIs provide a unique URL for each supported version of the API, so that clients can control the timing of their migration to newer versions of the API.

Required Parameters

Most API methods have one or more required parameters. When the client provides an empty or null value for any required parameter, the Cisco TelePresence Exchange System will throw a missing parameter exception noting the missing parameter.

Error Handling

The Cisco TelePresence Exchange System API communicates an error condition to the client by returning an exception message instead of a response message. The exception message contains an error code and string field that provides additional details about the exception.

The Cisco TelePresence Exchange System API communicates an error condition to the client by returning an HTTP 500 response that contains a SOAP fault. The fault contains an error code and string field that provide additional details about the exception.

Queries

For services that retrieve information about data objects in the Cisco TelePresence Exchange System (such as rooms or meetings), the API provides a generalized query mechanism to allow clients to flexibly construct the desired queries. Simple and complex queries are supported. A null query is interpreted as a request to return all of the entities.