HTTP Based APIs

The world of APIs is full of concepts that are not immediately obvious to those without software development backgrounds, and terms like REST, RPC, XML, JSON, SOAP, WDSL, etc. can be initially overwhelming. Reviewing some of the common characteristics found in many of today’s HTTP based APIs can provide a solid foundation for further research on more advanced topics such as RESTful API design.

The following high-level description aims to provide a basic understanding of the components that are typically used to describe an API’s design and hence the critical information needed for a successful API integration.

Who: API Authentication

Typically, APIs are authenticated as they are providing access to data programmatically that would otherwise only be available through a user login workflow. There are many different approaches to authenticating and authorizing API access and these often differ based on the class of data being accessed.

Some of the most common API authorization techniques used in API design are:

• Basic Authorization (presented in HTTP Header – Base64 user:password)
• API Key (presented in HTTP header or in API payload)
• OAuth 2.0 (Authorization framework for authorizing access to your data)

Deep discussion of each of these authorization options is outside of the scope of this overview document but given the support for OAuth2-based authorization in ClearPass, the following section will discuss the technology and how it is applied to the new ClearPass API surface.

Where: URL Location

Anyone wanting to interact with an API needs to know where to find the API server and importantly the URL path to the resource they are interested in. This is no different to a URL that would be typed into a web browser and the API documentation should detail where to find the resource you wish to interact with.

All of the ClearPass APIs can be accessed from the root location of /api from any of the nodes in your ClearPass cluster. As with any many of the functions within the ClearPass cluster deployments, read-access is available from all nodes in the cluster and ClearPass will internally proxy any write requests back to the Publisher node to ensure database consistency.

The following are examples of published API endpoints available from the ClearPass server as part of the 6.6 release.

How: HTTP Method

The HTTP method of an API describes how the server is expecting to receive the API request. A web browser by default is using a HTTP GET when downloading a web page and a HTTP POST when a user fills out a form and submits it to a server. APIs work in a very similar fashion to the web browser with the additional capability of being able to take advantage of other HTTP methods such as PUT (replace an object on the server), DELETE (remove an object on the server), or potentially PATCH (update an object on the server). Using the HTTP method to signal the intent of an API call is at the heart of the REST API design principal which is considered a best practice for modern API design.
The ClearPass APIs have adopted this design pattern of leveraging the HTTP method to indicate the intent of the API transaction. For example, the following table shows how the HTTP method can be applied to the /api/guest endpoint.

What: API Payload / Conten

The API content needs to be presented in a format that can be understood by the server. The specifics of the format are detailed in the API documentation. Some of the more common formats supported by APIs are:

• JSON (application/json)
• XML (application/xml)
• Form Encoded (application/x-www-form-urlencoded)
• Plain Text (text/plain)
  Also included in the list above is the value that needs to be included the HTTP Content-Type header so the API server knows what format you are sending in the API payload.

The ClearPass APIs are designed to expect the JSON Content-Type when the API call requires a HTTP body to be submitted (typically in unsafe operations such as POST, PUT, PATCH and DELETE).

API Documentation

Detailed documentation is available for the ClearPass APIs by clicking on the API Explorer link from the top right hand corner of the API Services configuration page from the Administration > API Services > API Clients page.

Alternatively, the documentation can be directly accessed from the following URL:

http://<clearpass.hostname>/api-docs

Accessing this page will display a catalog of available API entry points based on the various sub-systems of ClearPass that are currently exposed through the HTTP APIs.

Selecting one of the API entry points will then display the interactive API document for all of the API methods available for that ClearPass resource. The following screenshot shows the example of the ClearPass Guest resource and the API methods available.

API Configuration Options

Several global configuration options can be modified by browsing to the Administration > Plugin Manager menu option of the ClearPass Guest administrative interface and clicking on the Configuration option of the API Framework plugin.

The resulting page has options such as token lifetimes, logging levels and support for cross origin access typically associated with client side technologies such as javascript.

Default Lifetimes

Although token lifetimes can be configured on an individual basis for each API Client defined from the Administration > API Services > API Client configuration page, the global default token lifetimes can be updated from the plugin configuration.

Logging

During development of a new application that is leveraging the ClearPass APIs, there may be a requirement to increase the logging level from the default Standard (recommended) logging detail. This level of detail can be updated from the plugin configuration and the log output is available from the Administration > Support > Application Log menu option.

It is recommended that post any development testing of APIs that the logging level be returned to the default standard (basic) logging detail.

Cross Origin Resource Sharing (CORS) Support

The ClearPass APIs provide an option to enable server side support for Cross Origin Resource Sharing by specifying a allowlist of either individual servers or domains that should be permitted to access the API resources from a browser interface even though the initial webpage did not originate from the ClearPass server.

Modern web browsers have inbuilt security to protect users from malicious websites that attempt to access 3rd-party websites (or post data to) whilst a user is browsing their intended destination. By enabling the CORS support on ClearPass, the APIs can be accessed in this manner. This is typically used in development environments where a local webserver on the development host is used to temporarily host the basic HTML, CSS, etc. whilst the content is drawn from the API responses.
As noted in the user interface screenshot above, wildcards can be used to nominate an entire domain or potentially allowlist all origins during a development and testing phase. For a production deployment, it is recommended that only specific hosts or known domains be included in the CORS allowlist.

Arbitrary Sort

By default, not all fields available in the API calls can be sorted upon. Enabling this capability has performance implications if the API calls return large numbers of objects.

Summary

The following table summarizes the various API conventions that make up the ClearPass HTTP based APIs.