Introduction to Historian APIs

Important: You do not have the latest version of Historian! You are missing out on the newest capabilities and enhanced security. For information on all the latest features, see the Historian product page. For more information on upgrades, contact your GE Digital sales agent or e-mail GE Digital Sales Support. For the most up-to-date documentation, go here.

About this Book

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.

Important: Port 8443 is used in examples and sample code throughout the e-book. If you copy and paste the sample code from this document, you must change this port to your installed port.
See the following topics for more information:

About Security and Authentication

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.

Standards

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.

Important: Do not create your own URIs. Instead, use the links in this document and in the responses to navigate between resources.

API Methods

The Historian APIs use GET, POST, PUT, and DELETE methods.
Method Usage
GET Retrieves a resource.
POST Creates (or adds) a resource.
PUT Updates a resource.
DELETE Removes a resource.

API Status Messages

In its use of the following HTTP status codes, the Historian API services adhere as closely as possible to standard HTTP and REST conventions.
Status Code Usage
200 OK Success message. The request has completed.
201 Created Success message. A new resource has been created. The resource URI is available from the location header in the response.
204 No Content Success message. An update to an existing resource has been applied.
400 Bad Request Error message. The request was malformed. The response body provides additional information.
401 Unauthorized Error message. Either you are not authenticated, or the authentication is incorrect. You must re-authenticate and try again.
403 Forbidden Error message. You do not have permission to access this resource.
404 Not Found Error message. The requested resource does not exist.
500 Internal Error Error message. The server encountered an unexpected condition that prevented it from fulfilling the request.