Introduction to Historian APIs

Historian is a high performance data archiving system designed to collect, store, and retrieve time-based information at extremely high speed efficiently. The Historian environment provides a set of REST APIs to query data from the archives.

This document provides links for setting up your development environment, as well as information for getting started with the Historian services and their associated APIs.

For security purposes, Historian uses the User Account and Authentication (UAA) service as a trusted source of tokens issued for authentication. The UAA is a multi-tenant identity management service, used in Cloud Foundry, but also available as a standalone OAuth2 server. Its primary role is as an OAuth2 provider, issuing tokens for client applications to use when they act on behalf of Cloud Foundry users. It can also authenticate users with Cloud Foundry credentials, and can act as an SSO service using those credentials, or others. It contains endpoints for managing user accounts, registering OAuth2 clients, and other management functions.

The following diagram shows how the UAA Server functions with a Python REST client:

Figure: UAA Server and Python REST Client

Authorization

For exchanging data between the client-server system, user authentication is required. Once you have provided your client credentials, an access or bearer token is generated. This token is used for the REST APIs.

cURL command format for generating an oauth token: curl -u <Client-Id>:<Client-secret> https://<nodename>:8443/uaa/oauth/token -d 'grant_type=client_credentials'

Sample cURL command: curl -u admin:adminsecret https://<nodename>:8443/uaa/oauth/token -d 'grant_type=client_credentials'

If 'grant_type=client_credentials' does not work, use 'grant_type=password'.

Example:

curl -u user1:mypassword http://WIN-2T4JG45H2TI:8080/uaa/oauth/token -d grant_type=password

In the following image, the actual token text is blurred for security concerns.

Figure: OAuth Access Token Sample

Client applications can access data using service REST API endpoints. Your application makes an HTTP request and parses the response. You can use any web-development language to access the APIs.

Historian APIs use a REST application architecture constrained by Hypermedia as the Engine of Application State (HATEOAS) that distinguishes it from most other network application architectures. Therefore, a client interacts with a network application entirely through hypermedia provided dynamically by application servers. The REST client doesn't need prior knowledge about how to interact with a particular application or server beyond a basic understanding of hypermedia.

As defined by the query parameters, the Historian APIs use "search" functions to access raw data using cURL and HTTP, while responses are in JSON format.

cURL is a command-line utility used to transfer data from or to a server, using one of the supported protocols, such as DICT, FILE, FTP, FTPS, GOPHER, HTTP, HTTPS, IMAP, IMAPS, LDAP,LDAPS, POP3, POP3S, RTMP, RTSP, SCP, SFTP, SMTP, SMTPS, TELNET and TFTP. The command is designed to work without user interaction.

cURL offers many useful functions such as proxy support, user authentication, FTP upload, HTTP post, SSL connections, cookies, file transfer resume, user and password authentication, and more.

You can run the sample commands provided in this document from Bash on Windows in the Windows operating system, and also in Linux Shell in the Linux operating system.

As a prerequisite, make sure you install cURL on your system, if it is not already installed. Run the curl --version command on Windows Bash or Linux shell to check if cURL is installed on your system.