API Overview

CAP API (CAPI) provides endpoints for direct, programmatic access to data that simplify the integration of external systems via standard web protocols.

Communicating with the API

Most endpoints can be accessed via HTTP GET requests. Parameters, if any, should be supplied with the query string. Responses consist of JSON serialized object data that should be interpreted according to the specifications outlined in the documentation.

Some endpoints require HTTP POST. Data for POST method calls should be included in the request body.

HTTP clients that are included in most modern development frameworks should be compatible with the API, as are all major browsers. Many common applications also have the capability to connect with CAPI and transform response data. This allows for the abstraction of low-level communication details. For example, Microsoft Excel can retrieve API data through Power Query.

Authentication and Authorization

Prior to filling a request, CAPI will authenticate the origin and verify authorization to execute the given endpoint specified. Anonymous requests or requests to execute endpoints for which the authenticated security principal has not been granted access will result in an HTTP 401 Unauthorized response.

Authentication refers to the process of validating the identity of the requester. CAPI supports the following authentication methods:

• Basic authentication
  • CAPI support basic authentication as defined by IETF RFC 7617.
  • Requests should include an HTTP Authorization header that consists of the word “Basic” followed by a space and then the Base64 encoded credentials of the security principal.
  • Credentials should be supplied as a username and password separated by a colon delimiter (e.g. “username:password”).
  • As per the example outlined in the RFC, authentication of user “Aladdin” with password “open sesame” would require an Authorization header that consists of “Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==”.
• Session authentication
  • Clients can establish an authenticated session via the Login API endpoint. This endpoint is special in that it does not require prior authentication in order to execute.
  • Upon authentication, an authentication cookie will be returned that should be included in subsequent requests to the API.

Scope

CAPI currently exposes a very limited subset of CAP data. In addition, only a select few properties of exposed data objects are accessible. Requests for inclusion of additional data objects and properties will be evaluated on a case-by-case basis as they are received.