Introducing the JavaScript API

The TrustID Javascript API provides access to the TrustID Cloud at two levels:

  • The low-level Javascript API operates on raw JSON request and response objects and has the lowest number of abstractions.

  • The high-level Javascript API provides an easier access model to the TrustID Cloud and provides a rich data model around applications and documents.

This section focuses on the high-level Javascript API. For simplicity, the low-level parts are generally not described.

The TrustID Cloud API is session-based, meaning that a user session must be obtained (using username and password authentication) before any subsequent API calls can be made.

Note

See Introducing the Raw API for details of the Raw API.

See also

Authentication for more on authentication.

Supported Platforms

The TrustID Javascript Library is supported by all modern browsers. Some browsers do not support Promises, which are required to use the TrustID Javascript API. However, there are poly-fill implementations available for older browsers.

The TrustID Javascript Library can also be used on node.js. For more information, see Node.js.

The TrustID Javascript Library can be used with React Native in the same way it is used in the browser. For details, see React Native.

API Object

Access to the high-level Javascript API is provided by the Api.constructor object, for example:

var api = new TVS.Api();
api.login('username', 'password', function(response) {
    // .. response ok
});

This connects to the production system of the TrustID Cloud. For testing purposes, you may want to connect to your own installation of the TrustID Cloud by simply passing the full URL into the constructor function as the first argument:

var api = new TVS.Api('{{server}}');
api.login('username', 'password', function(response) {
    // .. response ok
});

Note

Replace username and password with the corresponding user credentials that you received from TrustID, or with credentials that match your own installation of the TrustID Cloud.

Promises

The TrustID Javascript API is based on the concept of promises. A promise is an object representation that captures an operation that has not necessarily been completed yet but will capture the result (or error state) of the operation when it completes.

Promises have the following key concepts:

  • A promise can only succeed or fail once. It cannot succeed or fail twice, neither can it switch from success to failure or vice versa.

  • If a promise has succeeded or failed, and you later add a success or failure callback, the correct callback will be called, even though the event took place earlier.

A promise can be used as shown below:

var api = new TVS.Api();
api.requestSomethingAsync().then(function(response) {
    // ... success ...
}, function(response) {
    // ... error ...
});

We execute an asynchronous operation through the Api.constructor object and then do something in the success case and something else in the error case. Because the operation returns a promise object, multiple operations can be chained together, for example:

var api = new TVS.Api();
api.requestSomethingAsync1().then(function(response1) {
    console.log('response1:', response1);
    return api.requestSomethingAsync2();
}).then(function(response2) {
    console.log('response2:', response2);
    // ...
}).catch(function(response) {
    console.log('error:', response);
});

In this example we request two things, where both operations are executed asynchronously. Because the system is based on promises, we can simply chain those operations together with the then() function. Here requestSomethingAsync1 is executed asynchronously and then requestSomethingAsync2 is executed once the previous operation has succeeded.

Note

The TrustID Javascript API does not provide a poly-fill implementation for promises in case the environment or browser does not provide support for promises by default. All modern browsers support promises.

If you need a poly-fill implementation for promises, see Promise.

See also

For more general information about how to use promises, see www.promisejs.org.

Error Response

An API response usually contains the exact information that was requested and does not necessarily contain any additional metadata. However, in an error case, the original JSON response from the TrustID Cloud is passed to the error handler, for example:

var api = new TVS.Api();
api.login('admin', 'password').then(function(loginResponse) {
    // ...
}, function(json) {
   console.log('error:', json.Message);
});

All error responses contain the following information:

{
    Success: false,          // success or failure?
    SessionExpired: false,   // true, if session has expired
    AccessDenied: false,     // true, if access has been denied
    Locked: false,           // true, if resource was locked
    Message: "...",          // Error message (text)
}

When an error occurs Success is always false and Message contains the full-text description of the error message. In addition, other flags might indicate some more details why the operation went wrong. For example, SessionExpired is set to true if access was denied because the session has timed out.

This list describes the response properties and their meaning in case of an error condition:

Success

true if the operation executed successfully, false if an error occurred.

SessionExpired

true if the API session identifier is invalid or the corresponding session has expired.

AccessDenied

true if access to a specific resource has been denied. This is usually due to insufficient user permissions.

Locked

true if access to a specific resource has been denied, because the resource is currently locked by another API session so cannot be modified.

Message

A full description of the error message.

Node.js

The TrustID Javascript Library can be used with node.js. The only difference is that tvsapi.node.min.js must be used instead of tvsapi.min.js. For example:

var TVS = require('lib/tvsapi.node.min.js');

var api = new TVS.Api();
api.login('username', 'password').then(function() {
    return api.queryArchiveContainer();
}).then(function(queryResults) {
    // list of applications...
    console.log('result count:', queryResults.TotalRecords);
}).catch(function(error) {
    console.log('error:', error);
});

See also

For more information on node.js, see the Node.js Documentation.

React Native

The TrustID Javascript API can be used in the context of React-Native in the same way as it is used in the browser. For example:

import React from 'react';
import { StyleSheet, Text, View } from 'react-native';
import TVS from './tvsapi.min.js';

export default class App extends React.Component {
    constructor(props) {
        super(props);
        this.state = {count: 0};

        // search visible results...
        var api = new TVS.Api();
        api.login('username', 'password').then(function() {
            return api.queryArchiveContainer();
        }).then(function(queryResults) {
         this.setState(previousState => {
           return {count: queryResults.TotalRecords};
           });
         }.bind(this));
        }

    render() {
        return (
            "<View style={styles.container}><Text>You have {this.state.count} applications results available.</Text></View>"
        );
    }
}

const styles = StyleSheet.create({
    container: {
        flex: 1,
        backgroundColor: '#fff',
        alignItems: 'center',
        justifyContent: 'center',
    },
});

This example uses ES6 syntax and presents a message on the screen about how many processed applications are currently visible to the user.

See also

For more information on React Native, see the React Native Documentation.