Up until now, you have used the MMP (CLI) and web-based GUI to configure all CMS functions. For some small deployments, this may be all you need. However, for more advanced deployments, configuration via the API is required. Even in smaller deployments, it is useful to be comfortable with the basics of API configuration. You may never need to create a full-blown application for interacting with CMS programatically, but understanding API basics is critical to many functions on CMS that are not exposed via any of the other administrative interfaces.
Traditionally, an API, or Application Programming Interface, is a set of routines, protocols, and tools for building software applications. It is also a specification as to how software applications can interact. In some sense, it is similar to the set of commands you can run and results you get back with a command-line interface. The difference is that a CLI generates output that is generally unstructured and easy for humans to read. APIs generate structured output that makes it easy for other programs to process and interpret that data. With the right tools, you can manually interact with the API and easily read and interpret the data.
With a CLI, you can often enter ? or some other help flag to get more information about what commands are available. That doesn't exist in an API; therefore, the API developer's guide is crucial to understanding what commands are available and how to use them. You can view the API Reference Guide here.
Cisco Meeting Server relies on a Representational State Transfer (REST) API. It uses the HTTP (or HTTPS) protocol as the underlying transport and is a stateless, client-server protocol, which means that if you're familiar with web-based URLs and their structure, you will easily be able understand REST. In REST, there are 4 supported types of operations, called verbs: GET, POST, PUT, and DELETE.
Most REST APIs treat these verbs similarly. Here is what they do in the CMS API:
For example, if you want to query the system status for the uptime and software version, you would send a GET request to the CMS server. The API reference tells you that the uptime can be found by using the GET method on /system/status. Below is an exceprt from the CMS API Guide:
For the CMS API (and many RESTful APIs) all of these commands require /api/v1 as the base URL. This is documented in the API reference guide. The full URL to get the uptime of cms1a is therefore https://cms1a.pod2.cms.lab:8443/api/v1/system/status (username: password: ). You must use port 8443 because that is the Web Admin port you configured earlier. If you go to this link using a standard web browser, it will ask you to authenticate. You can use the same admin credentials you have been using for Web Admin. Once you do, you will get a result in XML format.
You can use a web browser to send basic GET requests like the one above, but for more complicated requests and to send a POST, PUT, or DELETE, you must use different tools. You could write a program using a variety of programming languages (Python, Java, .NET, and so on...), but there are ways to access the API without having to write a line of code. There are many applications available that allow you to interact with a REST API. One such application, that you will use in this lab, is called Postman. (Postman has already been installed for you, but for your reference, you can download Postman at https://www.getpostman.com/.)
The default admin user has full access to the API, however it is best practice to create a dedicated user for API access. This is done from the MMP (CLI). Follow these steps to add an API user on each of the servers. These users are locally-significant, so you must configure the API user on each server individually.
|Cisco Meeting Server Name||Password|
On cms1a, enter the commandto create a user named apiadmin with the api role. The password should be set to :
You can use the user list command to confirm that the user was added.
The apiadmin account has already been created on CMS1b and CMS1c, so there is no need to configure anything there. Although the database is clustered in our lab, it is always a good practice to enable the same API account on all servers. For some parameters, such as ad-hoc conferencing and load balancing parameters, it is mandatory.
Now you will get familiarized with the Postman application.
The first thing you should do is have Postman ignore SSL certificate verification. If you are using certificates signed by a trusted CA in your production environment, you may not need to do this; however, for our lab this is necessary. Perform these steps:
Now you are ready to attempt your first request. Here is what the Postman UI should look like:
You have sent your first successful API GET request!