Cisco Unified Communications Domain Manager introduces a completely new approach to Unified Communications management that emphasizes the API as the common point of entry to the system. All Cisco Unified Communications Domain Manager functionality is available through the API, including the Cisco Unified Communications Domain Manager GUI itself, which uses the same API. Because the GUI uses the same API that is available to service providers externally, developers can use trace tools (such as Chrome developer tools) to learn details on the API schema, how the API operates, how to create, update, and delete objects, etc. Any operation performed by the Cisco Unified Communications Domain Manager GUI can be traced and replicated by an external client.

The API uses a well defined JSON schema with consistent meta-data across all device types integrated by Cisco Unified Communications Domain Manager , regardless of the devices native API format. For example, the native Cisco Unified Communications Domain Manager API is SOAP based XML but this is converted to object-oriented REST-based JSON, consistent with all other APIs in the Cisco Unified Communications Domain Manager system.

There are many APIs in the HCS system, including the native APIs for the devices integrated into Cisco Unified Communications Domain Manager (Cisco Hosted Collaboration Mediation Fulfillment, Cisco Unified Communications Domain Manager, Cisco Unity Connection), APIs for other devices not integrated in Cisco Unified Communications Domain Manager . These APIs are still available and can still be used for operations that aren't supported by Cisco Unified Communications Domain Manager orchestrated workflows. For example, Cisco Hosted Collaboration Mediation Fulfillment supports Prime Collaboration Assurance (PCA) configuration via API, but Cisco Unified Communications Domain Manager 10.1 does not currently support configuring PCA directly. Therefore, you can use the native Cisco Hosted Collaboration Mediation Fulfillment API for configuring PCA on Cisco Hosted Collaboration Mediation Fulfillment directly.

In order to understand the API, an understanding of two basic concepts is required:

• Models

• Hierarchy

The term "model" is used to describe the types of JSON objects fulfilling purposes such as defining data structures, containing data, defining GUI forms, mapping data from devices or other models. The system employs the following types of models:

• Data Models

• Device Models

• Domain Models

• Relations

• Views

Data in the system is represented using Data and Device models.

Device models are generated from the application API of entities that are provisioned on devices.

Domain models, relations and views wrap the Data or Device models by means of references to them.

Data models can be created and are stored in the database. Data models contain a JSON schema/metadata for the entities exposed by the underlying database. The schemas for the data models are stored in the database and represent the structure that instances of the data model conforms to.

Device models interface with devices and services on the system. For example:

• Unified CM device models interface with the Call Manager's AXL SOAP API.

• CUC device models interface with Unity Connection's RESTful API.

The ability to rapidly develop and deploy new device interfaces provides an extensible mechanism to add support for additional provisioning tasks or additional southbound integration into other business systems. Domain models act as "containers" of other data-, device- and domain models along with provisioning workflows to represent the management of a created feature.

Relations do not store data on the system. Instead, they relate groups of resource types such as device models, data models or other domain models.

Views provide a mechanism to define an arbitrary schema which can be used to define a user input screen.

A system hierarchy node is present at first startup of the system. Each entity that is attached to the hierarchy has an address represented by a PKID, that is defined as a standard URI. Hierarchies can be created under the system hierarchy node, because the hierarchy is exposed as a RESTful API. API calls are made with reference to the hierarchy.

For more information, refer to the Hierarchy section in the Cisco Unified Communications Domain Manager, Release 10.6(3) Planning and Install Guide.

The system uses a REST (Representational State Transfer) API. For details on this type of API, see for example:

• http:/​/​en.wikipedia.org/​wiki/​Representational_​state_​transfer

The system represent the reference of an entity in the system as http:/​/​en.wikipedia.org/​wiki/​HATEOAS (HATEOS). Each reference position is represented by an object pair PKID and href.

A client integrates with Cisco Unified Communications Domain Manager 10.6(x) entirely through hypermedia dynamically provided by the application and does not need any prior knowledge of how to interact with the system other than a generic understanding of hypermedia. This means that no http:/​/​en.wikipedia.org/​wiki/​Web_​Application_​Description_​Language is provided. This also means that the client and the application can be decoupled in a way that allows the application to evolve independently.

A client enters the the application through a simple fixed URL. All future actions the client may take are discovered within resource representations returned from the server

The URL tree information is obtained in the form of a list response from the application endpoint:

GET /api/?format=json

This response emulates the HierarchyNode list response and utilizes the parent and children in the meta references section of the response as discussed in Meta Data References.

The request and response patterns between service requester and Cisco Unified Communications Domain Manager 10.6(x) is summarized below.

For synchronous operations:

1. Service Requestor sends an accessor (e.g. Get, List) request with request parameters.

2. Either:

   1. responds synchronously with a Get/List response.

   2. responds synchronously with a fault response.

For asynchronous operations:

1. Service Requestor sends a mutator (e.g. Add, Modify, Delete) request with parameters.

2. The Add/Update/Delete transaction is scheduled in the transaction queue with a transactionID.

3. Responds synchronously with either:

   1. An Add/Update/Delete response and a transactionID.

   2. A fault response.

4. The external system either:

   1. Polls the system to retrieve the status of the transaction as needed, or

   2. Specifies a callback URL (with an optional username and password if the interface is secured (recommended)) and waits for a asynchronous transaction status callback (recommended).

      When the transaction completes, Cisco Unified Communications Domain Manager 10.6(x) sends an async transaction status callback message to the callback URL specified in the request.

The Cisco Unified Communications Domain Manager 10.6(x) API accesses system resources or tools.

• Resources

The general structure of an API URL for accessing a system resource (an endpoint) is:

Method https://servername/api/Version/Resource/Action/?Parameters

Where:

Method

[GET|POST|DELETE|PUT|PATCH]

Servername

The installation server determines the base URL, e.g. https://servername. In a cluster environment, this is the address of the web proxy node. Refer to the Install Guide for cluster deployment information.

Version

(int:major[.int:minor])/

Resource

(str:modeltype/str:modelname)[/pkid]

Action

[add|create|list|update|remove|configuration_template|field_display_policy|
 export_bulkload_template|bulk_update|clone|move|export|execute|translation|
 migration|help|+tag|+tag_version|+[non-CRUD operation|CustomWF|
 other custom actions (see API Reference Guides)]]

Parameters

[(str:api parameter)[&(str:api parameter)...]]

The HTTP methods and parameters are described in relevant sections. The different resources supported in the system are described in the API Reference Guides.

• Tools

For tools, the general structure of the URL structure is for example:

[GET|POST] /api/tool/(str:tool_name)/

The system API supports the following format HTTP headers when handling and responding to requests.

The system controls access to its service through HTTP basic authentication. The technique is defined in section 11.1 of RFC1945 which is simple to implement, uses standard HTTP headers.

The HTTP Basic Access Authentication requires authorization credentials in the form of a user name and password before granting access to resources in the system. The username and password are passed as Base64 encoded text in the header of API requests.

The HTTP header format for authentication is defined in the table below.

For example:

The Base64 encoded credentials for user name of joe and a password of bloggs.

For example, from a command line (note the removal of the new line in the echo command):

$ echo -n "joe:bloggs" | base64
am9lOmJsb2dncw==

the header is:

Authorization: Basic am9lOmJsb2dncw==

For example, using curl:

curl -k -H "Authorization: Basic am9lOmJsb2dncw==" 'https://hostname/api/data/MyModel/'

It is required that all requests be conducted over a secure session, such as HTTPS or SSL.

A Cisco Unified Communications Domain Manager 10.6(x) self-signed certificate needs to be installed into a local trust store of the client application.

The access profile of a user determines whether he or she can perform a given operation on a model. The user can also only access items below the position they are defined in the hierarchy.

The API supports the following HTTP methods:

GET

• Used to query a resource or a list of resource.

POST

• Used to create a new resource.

• The data is submitted as a JSON object.

• The return value is the PKID of the resource.

PUT

• Used to update the data of a resource.

• The resource URL includes the resource PKID.

• The data to be updated is submitted as a JSON object.

PATCH

• Used to update the data of a resource.

• PATCH request body in JSON Patch format

• Content-Type is "application/json-patch+json"

• JSON Patch: http:/​/​tools.ietf.org/​html/​rfc6902

DELETE

• Used to delete a resource.

• The resource URL includes the resource PKID.

• The DELETE method can also be used to delete multiple resources on one request as a "bulk delete".

For PUT methods the resource data is replaced with the data specified in the request. All fields of the resource are replaced with the fields in the request.

This means that:

• Fields not present in the request that are present in the resource are dropped from the resource.

• Fields present in the request that are not present in the resource are appended to the resource.

• The data of fields present in the request is used to update fields that already exist in the resource.