Live API

Last modified by michaely on 2021/09/10 23:34

This page is currently being written. Although the information below is probably accurate, it may not be complete or may have errors.

The information on this page applies to iSymphony 3.2+.

Description

The Live API provides information about the real time state of the iSymphony server, and exposes resources used to execute actions, via a HTTP REST interface. This API can be used to integrate external applications with iSymphony, by providing live information about users and call state in the system, and at the same time allowing those applications to preform actions. The information and actions provided are similar to those found in the client interface. In conjunction with the CRM Widget, this API can also be used to create custom widgets for the iSymphony client interface.

On this page:

The [toc] macro is a standalone macro and it cannot be used inline. Click on this message for details.
This macro generates standalone content. As a consequence you need to make sure to use a syntax that separates your macro from the content before and after it so that it's on a line by itself. For example in XWiki Syntax 2.0+ this means having 2 newline characters (a.k.a line breaks) separating your macro from the content before and after it.

Resource Instance IDs

Every instance of a REST resource specifies a UUID, that serves as a unique identifier for that specific instance of the resource. These UUIDs can be used in REST URLs to access a specific instance of a resource. These UUIDs are the same ids that are used to identify objects in the Event API, allowing collaboration between the Live REST API and the Event API.

For example, the URL below provides access to an extension instance with a UUID of ef2faba9-8557-49c1-9ffc-5a71f41c7a23, in a core server with a UUID of ca5de6c4-17bd-46ce-95a2-8b29c7812ca4:

http://localhost:58080/communication_manager/rest/live/coreServers/ca5de6c4-17bd-46ce-95a2-8b29c7812ca4/extensions/ef2faba9-8557-49c1-9ffc-5a71f41c7a23

Note on UUID persistance

The UUIDs do not persist across restarts of the iSymphony server. If the server is restarted, the objects will contain new UUIDs. Also, if an object is destroyed then re-added, even with the same configuration, the UUID that represents that object will be different from the original.

Configuration IDs

Some resource instances will provide configuration ids, that specify the id of the configuration object that is related to the live object. These are the same ids used to access resources in the REST Configuration API, allowing collaboration between the REST Live API and the REST Configuration API.

Accessing Resource Instances By Symbolic Name

In addition to accessing resource instances by UUID, resource instances can also be accessed by their symbolic name. Most, but not all resources contain a symbolic name. The path section getByName can be used to access a resource instance by it symbolic name. Documentation for a specific resource will specify, if the resource can be accessed by symbolic name, and what the symbolic name property is.

Examples

The following path will access an extension with extension number 4224, in a core server with a slug of default.

http://localhost:58080/communication_manager/rest/live/coreServers/getByName/default/extensions/getByName/4224

You can mix and match UUIDs and getByName in the REST URLs, like so:

http://localhost:58080/communication_manager/rest/live/coreServers/getByName/default/extensions/ef2faba9-8557-49c1-9ffc-5a71f41c7a23

Document Notation

When a parent resource path can be access by UUID and getByName, the path in the documentation will specify the following format:

[{UUID} | getByName/{symbolic_name}]

This specifies that the instance can be accessed via "UUID" OR "getByName/symbolic_name". {UUID} and {symbolic_name} will be replaced with more specific names.

REST Resources

The Live API exposes several REST resources, that allow access to the current state of specific objects in the system. All current live resources are listed below. Details concerning each resource, and their actions, can be found within the individual resource documentation pages.

Resource List

Notes on Resource Documentation

Due to the interdependent nature of resources in the system, the resource path information in the documentation is split into several sections. Paths in a specific section may relate to, or require, paths specified in other sections.

Root Resource Paths : Specifies paths that can be used to access sets (multiple instances) of a resource, in relation to a parent resource.
Instance Resource Paths : Specifies paths that can be used to access a specific instance of a resource. These paths require a Root Resource Path, in most cases, but not all.
Sub Resource Paths : Specifies paths that provide access to the child resources, of a specific resource instance. These paths require an Instance Resource Path.
Action Paths: Specifies paths that are used to perform actions on a specific resource instance. These paths require an Instance Resource Path.