Introducing the Raw API

The TrustID Raw API is based on JSON-encoded request and response messages on top of HTTP. To summarise:

  1. A request message is sent to the TrustID Cloud.

  2. The TrustID Cloud processes the request.

  3. The TrustID Cloud sends back a response message.

This documentation provides both an overview and detailed information about most of the underlying raw request and response messages used to interface with the TrustID Cloud.

Note

TrustID also provides the higher-level Javascript API which is easier to use because it provides some abstractions and utility functions which are not available through the Raw API. See Introducing the JavaScript API for more information.

Supported Platforms

The Raw API does not have any specific requirements other than being able to send and decode JSON-encoded response messages.

TrustID Cloud Endpoint Address

By default, the HTTP base endpoint address of the TrustID Cloud is:

If you are running the TrustID Cloud locally the base endpoint address might be this:

{{server}}/VPE/

A good way to test that the TrustID Cloud is running is to copy and paste the following URL into the address bar of your browser (we assume in this example that you have the TrustID Cloud running locally):

{{server}}/VPE/session/testConnection/

This should invoke the TrustID Cloud endpoint /session/testConnection/. You should see the following response message:

{
    "Success": true,
    "Message": "Operation executed successfully."
}

The purpose of this endpoint is to test whether the TrustID Cloud is available. It takes an empty GET or POST request and delivers a JSON-encoded HTTP response message showing whether the service is available or not.

Note

As shown later, most service endpoints require a JSON-encoded request message that is sent to the TrustID Cloud as the payload of an HTTP POST message (rather than the GET that is used in the above example).

Testing the Raw API

In the above section we could copy and paste the URL into a browser when testing the connectivity to the TrustID Cloud. This is not possible for most service endpoints because most of these endpoints require a POST request, where the request payload is a JSON-encoded request message.

A number of methods and tools are available to test the Raw API. If you use the Google Chrome browser, you could use the Restlet Client for example; this allows you to submit POST messages easily.

Alternatively, you could simply write a small HTML file that submits the request object via POST as follows:

<html>
<head>
    <style>
        textarea,
        button {
            display: block;
        }

        textarea {
            font-family: monospace;
            font-size: 14px;
        }
    </style>
</head>
<body>
    <h1>TrustID TrustID Cloud Post Example</h1>
    <form method="POST" enctype='text/plain' action="{{server}}/VPE/session/login/">
        <textarea rows="40" cols="80">
{
    "DeviceId": "device-id",
    "Username": "admin",
    "Password": "********"
}
        </textarea>
        <button type="submit">Submit</button>
    </form>
</body>
</html>

This looks like a normal HTML form, except that the encoding type (enctype) is set to text/plain. This ensures that the form content is not encoded as name/value pairs as is usual (for example application/x-www-form-urlencoded) but submitted to the server in plain text instead.

Request Message

Apart from testing connectivity, most service endpoints require user authentication. We use user authentication in the following examples to demonstrate request messages.

A minimum request message contains two properties:

  • Session identifier - this can be omitted if the purpose of the endpoint is to obtain a valid session identifier.

  • Device identifier - any user-defined string that represents the device in use. This must remain constant for the duration of a session. So if a particular device identifier is chosen when obtaining a valid session identifier, the device identifier cannot change over the lifetime of the session identifier.

    In practice, this can be a random number that is generated when establishing a new session and stored on the client-side for the lifespan of that session.

To obtain a new session identifier, we can use the /session/login/ endpoint and post the following payload as the request message:

POST {{server}}/VPE/session/login/
Content-Type: application/json

{
    "DeviceId": "device-id",
    "Username": "admin",
    "Password": "********"
}

The service should answer with the following response message:

{
    "Success": true,
    "Message": "Operation executed successfully.",
    "SessionId": "C7AB16FD95CDE98DE3226A71A96A7557BE0CC8854199F2D1578273D6E4AF9ABF",
    ...
}

See also

Authentication for details of how the endpoint’s actual response contains much more information than the example shows.

/session/login/ for reference information about the endpoint.

Note

The session identifier provided is just an example and almost certainly differs from that you would get when executing this example yourself.

Response Message

Most service endpoints respond with a JSON-encoded response message that contains general information about the success or failure of the operation as well as information about its result.

For example, the /session/login/ endpoint responds with two elements:

  • a JSON-message that encodes the success of the operation using its Success and Message properties (as any other endpoint does).

  • information about the result of the operation, for example by providing the new session identifier using the SessionId property.

{
    "Message": "Operation executed successfully.",   // message
    "Success": true,                                 // success

    // actual response payload, e.g. session identifier
    "SessionId": "...",
    ...
}

Error Response

If a service operation fails for any reason, the Success property of the response message is false and the Message property contains a human-readable message describing the failure.

In addition, further properties of the response message might indicate some additional information about the cause of the failure. For example, if the operation failed because the session expired, the property SessionExpired is set to true.

{
    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)
}

The following list provides more information about the response properties and the meaning of possible error conditions:

  • 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 or because the resource is currently locked by another API so cannot be modified.

  • Message - a full description of the error message.

Unique Identifiers

Examples of unique identifiers are Id, DocumentId, and ContainerId. All of these are guaranteed (to a very high probability) to be unique across different TrustID Cloud instances.

In particular, when importing records from one system into another, you can detect duplication by comparing corresponding identifiers.

JSON Date Format

Request and response messages encode date and time values in this format:

“/Date(ticks)/”

where ticks represent milliseconds since epoch (UTC). This format is the default encoding for date and/or time values in .NET when converting messages to JSON. See An Introduction to JavaScript Object Notation (JSON) in JavaScript and .NET for more information.