Relevant Webex resources:
Unity Connection has implemented the following APIs:
The difference in CUPI for administrators and CUPI for end users is in the rights required by the account accessing the system. System administration tasks, consequently, require an account with the System Administrator role (configured via the GUI under the User > Roles). Whereas CUPI for end users are accessible to end users for administering their own account, such as greetings, transfer rules, etc.
Aside from the Postman collection we have for testing, the Cisco Unity Provisioning API (CUPI) for administrator and end users has a published Web Application Description Language (WADL) that can be downloaded. This is an XML file that models the resources provided by the web service, similar to what the WSDL file does for the SOAP API. This file can be downloaded from the Unity server using the URL https://{UnityConnectionServer}/vmrest/application.wadl. This isn't available for all APIs, not even all of the Unity Connection APIs, but for these common administrative tasks, having this reference handy is extremely useful. Additionally, a schema is published on the server itself, accessible via https://{UnityConnectionServer}/vmrest/schema. This is especially useful in analyzing the types of data that may be returned for a given query.
Note: Make sure the entire file is downloaded. Usually it's best to use something like
curl or wget.
For example:
curl -k -u admin:C1sco.123 https://cuc1a.pod6.col.lab/vmrest/application.wadl -o application.wadl
Once downloaded either SoapUI or Postman can import this file (File > Import). In Postman, this loads a Collection, for which all
options are exposed. You can fill in the credentials at the Collection root and then easily perform queries,
checking/unchecking the options you intend to send.
In general, Unity Connection's APIs are fairly flexible. A field that is not understood is always ignored by the server, meaning if some setting is changed that exists in a newer version and that same setting is specified in an older one, the older server will simply ignore that data. As far as the query itself, the server will generally respond back with at 415 if the Content-Type header is not understood and a 302 if there is a connection attempt to an insecure (http) for that is redirected by the server to a secure (https) port.
In this lab, we only have one Unity Connection cluster, but if you have multiple, networked Unity Connection clusters, you can determine which cluster that user is located by querying the globalusers table. For example: GET http://{UnityConnectionServer}>/vmrest/globalusers?query=(alias%20is%jdoe)
For larger data queries, the rowsPerPage and pageNumber can be used to implement paging, thereby reducing the amount of data the server will have to respond with for a query. The query parameter, with its filtering options (dtmfaccessid startswith 855512) can further reduce the amount of data.
Regarding Unity Connection's performance, the system is able to process a maximum of 5 web application requests at one time. The throttle uses a global variable for this, so any request in any process using the throttle will count towards 1 of the 5. Any request that comes in while 5 or more others are processing will get queued and processed as soon as one of the active requests is complete. We can queue up to 255 requests (or the thread limit in tomcat, which is 150). As long as requests process at a rate of 1 request per second, the other requests will remain in the queue. If the requests start processing at a rate slower than 1 per second, the queue wait mechanism times out and the client will get a "server busy" (HTTP 503) response.
For troubleshooting, Unity Connection does provide VMREST micro traces, set on the Cisco Unity Connection
Serviceability page under Traces > Micro Traces. This generally requires
Debug-level traces and are written to the CUC Tomcat log trace file location (from the CLI:
file list activelog cuc/diag_Tomcat_* date detail
For example a GET request for the /version/product may look like:
10:29:20.548 |20085,,,VMREST,3,DEBUG [http-bio-443-exec-2] com.cisco.connection.rest.SecurityFilter#doFilter - IMS result code: 0
10:29:20.558 |20085,,,VMREST,3,DEBUG [http-bio-443-exec-2] com.cisco.connection.rest.CorsFilter#doFilter - doFilter - The request is not a CORS request as request is from same origin: null . Delegating to next filter for further processing.
10:29:20.558 |20085,,,VMREST,3,DEBUG [http-bio-443-exec-2] com.cisco.connection.rest.RequestFilter#filter - REQUEST GET version/product/
10:29:22.004 |20085,,,VMREST,3,DEBUG [http-bio-443-exec-2] com.cisco.connection.rest.VersionInformationRestImpl#checkProductVersion - Installed product version: 12.5.1.14900-45
Cisco Meeting Server API access is available via the webadmin feature. This is enabled on a Callbridge server and then uses a user account--either an administrator or minimally an api user. For example, you can add a user for api access via the CLI using the command: user add apiuser api, which then prompts for a password.
Aside from the official API documentation, Cisco Meeting Server has examples and code snippets on Devnet. From there you can download a Postman Collection for most of the CMS methods, as well as a Python SDK called Canopy. These items aren't necessarily maintained by Cisco on a per-release basis, but in general they are very helpful and can be extended for any additional API methods that are introduced. Cisco does maintains interactive API documentation at https://ciscocms.docs.apiary.io. This documentation and tool allows you to run mock queries and get results directly within the framework. At some point in the future, this will likely become the official API documentation repository for CMS.
The documentation does a good job explaining the object hierarchy in CMS, but there are some general considerations to point out with this API: