REST, which stands for REpresentational State Transfer, is the second type of web services architecture used in Cisco's Collaboration products. Unlike SOAP, there is no "REST standard" per-se. While SOAP is a well-defined protocol, RESTful APIs are a style that leverage existing standards such as HTTP, JSON, XML, and others to provide a web service. As a result, you will notice differences in how products implement REST APIs.
REST-compliant (RESTful) systems consist of a client and server that are always stateless. Although technically not mandatory, all REST-based APIs in Cisco Collaboration products use HTTP. In this model, a client sends a request to a server. This request has a path to a resource, which is a URL. It may also have query parameters after the URL, indicating some variable or setting. The ? character marks the end of the URL (the resource) and the start of these parameters. Each additional parameter is separated by the & character. For example: http://server:8443/api/v1/inventory?department=sales&product_id=1324&detail
The type of request is called a verb and there are four that are covered in this lab:
A REST request will include Headers, for things like authentication information and defining the data format of the payload, if any. Headers play an important role in authentication in REST APIs - specifically the Authorization header.
RESTful APIs may implement authentication and authorization in a variety of ways, or not at all. For example, the Cat Fact API at https://catfact.ninja/fact will return a JSON formatted body containing a random cat fact and doesn't require any authentication. Because no authentication is required and this particular API endpoint uses the GET verb, you can access it with a standard web browser. This is an example of a very simple REST API. As you will see, the APIs available in Cisco collaboration products are more complex than this, but they fundamentally work in the same way.
Cisco collaboration products make use of one of the two differnet mechanisms for authentication:
Basic Authentication, as the name implies, is the simplest mechanism available for authenticating an HTTP-based application. RESTful APIs make use of HTTP and can therefore use this as an authentication mechanism. You have already been using Basic Authentication in this lab, as the AXL SOAP API uses Basic Authentication. Basic Authentication simply sends a username and password along with every request in the Authorization header. The header value begins with the word "Basic" followed by a space and then the credentials. The credentials are the username and password concatenated together with a colon (:) character in between and then Base64 encoded. For example, the Authorization header for the username User1 with password mypassword would look like this:
Authorization: Basic VXNlcjE6bXlwYXNzd29yZA==
If you don't believe us, feel free to take the string VXNlcjE6bXlwYXNzd29yZA== and use any publically available Base64 decoder to decode the text back to the username and password.
Basic Authentication is primarily used on APIs provided by the on-premises collaboration products such as Unified CM, Unity Connection, and Cisco Meeting Server. It is important to transport any API calls using Basic Authentication over an encrypted connection (HTTPS) because an attacker who captures any request can obtain your username and password. One of the downsides to using Basic Authentication is that you need to share a username and password with whoever is implementing the application that is using the API. If specific restrictions on what that application can do are needed, they must be implemented at the user account level where the user itself is only allowed to perform specific tasks. A better way of authenticating and authorizing REST APIs is through the use of access tokens.
The REST APIs provided by Cisco Webex use access tokens for authenticating and authorizing API requests by leveraging the OAuth2 standard. Access tokens can come from a variety of sources, but they are all used in the same way: the HTTP Authorization header (the same one used for Basic Authentication) contains the word Bearer followed by a long string of characters that represents the access token. For example, the Authorization header for request may look something like this:
Authorization: Bearer CDc4KmFjMzAtMDA9jjauYWUkLWExMmEtYmU3MmZhMGNiN2VjYjab_AD92_039cfbf8-2732-8f82-0239-7283abef9283
The contents of the access token itself can vary from implementation to implementation. Some APIs that make use of access tokens use opaque tokens which means that the token itself is just an identifier and the system to which you pass the token must ask the authentication system whether the token is valid or not and what permissions the token has access to. Another token format is the JSON Web Token (JWT) format (pronounced "jot"). JWT tokens are self-contained and provide all the authentication information in the token itself. Webex APIs make use of both opaque tokens and JWT depending on the mechanism by which you obtain the token. The type of token is not of much importance to someone using an API because it is up to the service receiving the token to determine how to authorize the user based on the token, however because JWT are self-contained, you can use a decoder like the one on jwt.io to give you the contents of the token. Be careful using online tools like this because your token should be treated like a username / password. Someone who has the token can access any resources granted to that token.
Access tokens also typically have a set of Scopes associated with the token. A scope is a way to define a specific permission in the API. Scopes are completely implementation dependent and each API you find that uses tokens will have differnet levels of granularity in their scopes. For example, one API may just have a "readonly" scope and a "read-write" scope while other APIs may have specific scopes for different levels of access to individual resources - for example a scope that allow for reading only user accounts.
Cisco Webex has a variety of different access tokens available for different needs. We will start here by using a Personal Access Token which is a token that represents your user account in Webex. A Personal Access Token is authorized to do anything you as an individual user are allowed to do. This means that if you are an administrator, the token can perform administrative tasks, but if the token belongs to a standard user, it can only access resources that a non-admin user would have access to.
One of the biggest differences between Basic Authentication and access tokens is that access tokens typically have a limited lifetime. In other words, they expire after a certain amount of time after being granted. Some tokens can expire within minutes or hours while others could be valid for years. Webex Personal Access Tokens are only valid for 12 hours, so after 12 hours, you must generate a new token to continue using the API. If tokens are only valid for a short period of time, how do you stay logged in to an application using access tokens or how can you continue to use an API that requires access tokens without having to provide new credentials? This is made possible through the use of refresh tokens which can be used to request a new access token. We will discuss refresh tokens in more detail in a later section when we dive into service apps. For now, let's see how you can use a personal access token to make some simple API calls to the Webex APIs.
You can now explore some the features of a REST-based API by way of an example. While there are a number of tools that allow you to construct custom REST queries, such as Postman, the Cisco Webex documentation itself allows you to send API requests directly to Webex and examine the results. Let's take a look at querying a person.
In this example, you see not only a response code, but also the Body of the response which contains the user data with this email address (in some cases there is no data returned but simply the code, indicating that the request was successful or not). This is a JSON payload, with some indenting to make it more readable. Similar to XML, it is a serialization format. That is, JSON is a way of representing structured data in the form of a textual string, so it can be sent between client and server. JSON is not nearly as rigid or complex as XML. It looks very much like a Python dictionary, but it is not the same. Text data in JSON must be enclosed with double quotes (whereas in a Python string, single or double quotes would work), and while Python supports many data types, including custom ones, JSON supports very few (string, integer, array (list), a boolean, null, or another JSON object). Therefore, to change something into a JSON string, you often have to convert to these simpler types. Since this is such a common task, many Software Development Kits (SDKs), which are a set of tools that facilitates usages of specific APIs, will provide methods to export or convert their data in JSON format.