Cisco Meeting Server (CMS) has a rich REST-based API that allows configuration of nearly all settings, many of which can only be configured via the API, especially when working with clustered CMS systems. Any CMS server can have the WebAdmin service enabled, which also enabled the administrative GUI page. A separate account may be used for API access, or an admin account can be used.

The Cisco Meeting Server API documentation can be found here: https://www.cisco.com/c/en/us/support/conferencing/meeting-server/products-programming-reference-guides-list.html

CMS supports the regular GET, POST, PUT, and DELETE verbs to retrieve, create, modify, and delete an object. All of the requests will be sent to /api/v1. Responses could include 503, to indicate a busy condition, a 404, if the destination is not found, or other 4XX and 5XX response codes, which will are documented in an XML-encoded reply to the message body.

There are a few features to note:

• Responses to a GET request will generally include a payload in the text/xml format.
• Data in POST and PUT messages should be sent in x-www-form-urlencoded format and should have this Content-type specified in the header. This essentially places the key/value pairs as parameters in the URL. There is (so far) one documented exception to this, for custom layout templates, where a JSON payload is required, but this is not applicable in this lab.
• Failures are reported in a predictable XML format such as that below. These errors have more detailed explanations in the documentation. You can use this information to create a mapping, in order to provide better error reporting. As a simple example, userDoesNotExist is explained as: "You tried to modify or remove a user using an ID that did not correspond to a valid user".

To illustrate Meeting Server capabilities, you will configure the following using Postman:

1. Retrieve system status
2. Create a Space
3. Modify a Space
4. Retrieve Spaces
5. Delete a Space

Step 1 - Retrieve System Status

You already retrieved the system status of CMS in the REST overview section. You will repeat this using a Postman Collection just to make sure everything is set up.

1. In Postman, make sure at the left side of the screen, the side-bar is visible (otherwise select View > Toggle Sidebar).
2. Make sure the Collections tab is selected.
3. Below that, open the HOLCOL-2574 > Direct to Server > CMS folder.
4. Click on GET system_status, which should open in a new tab.
5. Click Send and you should see the status, similar to what was observed previously.

Step 2 - Create a Space

Creating a Space in CMS is fairly straightforward. A POST request is sent to /api/v1/coSpaces. Note that in the CMS API, Spaces are always called coSpaces, deriving the name from its origins with Acano. In the Header of the request, the Content-type must be specified as application/x-www-form-urlencoded. This will pass the information you enter in the Body section as part of the URL in the correct format. In this case, all of the key/value pairs will be encoded something like this to the URL itself:

        name=New%20Space&callId=5555&secondaryuri=5555&uri=space
    

So technically these are URL parameters instead of a payload as we have seen with JSON previously. But having the correct Content-type specified is significant. If the server does or does not expect a particular Content-type may determine the success of the query. As you can already see, even though both Unity Connection's CUPI and the CMS API are both REST-based, they have some significant differences in how the informtion is passed to them.

1. In the Postman HOLCOL-2574 collection, navigate to Direct to Server > CMS and click on Create coSpace, which should open in a new tab.
2. Examine the Header, which will have Content-Type set to application/x-www-form-urlencoded.
3. Now look at the Body tab. It will have some of the desired settings for this new Space in a table format. With the Body tab selected, at the right, you can click to toggle Bulk Edit mode, which will make the settings appear as follows (and can easily be copy/pasted instead of entered one at a time):
    

   name:New Space
   uri:space
   secondaryuri:5555
   
   

4. Click Send.
5. Verify that the reply back is a 200 OK
6. Notice that neither a pkid or object ID or anything was returned. Unlike CUPI, CMS puts this into the header of the reply. If you look at the reply, next to the selected Body tab, there will be a Headers tab. Click on it and you will see the reply headers, including a Location header that does, in fact, contain the URL of the created object. For example:
    

       /api/v1/coSpaces/2cb3a80a-51a4-4086-9487-fc06087e78ed
           

   Copy this object id (the coSpaceID) value from your Location header, since you will need to use it in the next step.
   

Step 3 - Modify a Space

Modifying the Space is similar as creating the Space, since you are sending data (with the desired changes), however that the Space ID will now be part of the URL.

1. In the Postman HOLCOL-2574 collection, navigate to Direct to Server > CMS and click on Modify coSpace.
2. Modify the URL so as to contain the coSpace ID (from the Location response header) from the previous step.
3. The Body simply instructs to change the name of the Space to "Modified Space" and updates the uri to "newspace".
   
4. Click Send and you receive a 200 response code.
   If you receive a 400 Bad Request with a coSpaceDoesNotExist failure message, that means the coSpace ID (from the Location response header) is not correct.

Step 4 - Retrieve Spaces

Retrieving the list of all Spaces is simply of sending a GET request to /api/v1/coSpaces.

1. In the Postman HOLCOL-2574 collection, navigate to Direct to Server > CMS and click on GET coSpaces.
2. In the request tab, click Send and you should see one coSpace, as part of a valid XML in the reply body.
    
   And here you can see the coSpace ID, which was only part of the Location reply header when created. Take note of this since you will need it in the next step.

You'll notice that this request was not very specific, in that it always retrieves the entire list of coSpaces unless a filter parameter is specified, for example, https://cms1a.pod6.col.lab:8443/api/v1/coSpaces?filter=pod
The problem that you will need to solve later, is that the filter above, pod is essentially searching coSpace names, URIs, and secondaryURIs for *pod*. So if the filter only contains a single letter, it is almost the same as getting the entire list. There is no way of specifying a specific user, without using that user's object ID.

A second consideration is that CMS can limit the number of items it returns. Currently the documentation states that the internal limit is 10, meaning if you have a 100-Space system and you send a request to GET /api/v1/coSpaces to retrieve them all, you will receive only 10 coSpaces in the reply, however, the total= value (see the reply above) will indicate the total number of matches (not the number returned). Using this total and the offset parameter, will allow us to get a "page" at a time, if you need to get a larger list of coSpaces. For example, if a GET /api/v1/coSpaces (with offset 0 implied) will return, say, the first 10; a GET /api/v1/coSpaces?offset=10 will retrieve from 11-20, etc.

Step 5 - Delete a Space

Deleting a Space simply requires the coSpace ID, which you have from the previous query.

1. In the Postman HOLCOL-2574 collection, navigate to Direct to Server > CMS click Delete coSpace.
2. Modify the URL so as to contain the coSpace ID from the previous step.
3. Click Send and you should receive a 200 OK. If you run the query again, you'll see a 400 Bad Request with a failure code of coSpaceDoesNotExist, because a Space with that coSpaceID had already been removed.

Now you are ready to look at notifications using Webex.