The Sentinel DataObject REST API

Sentinel exposes a number of data items via a REST-ful API using HTTP. The Sentinel data items are referred to as data objects; the API to access the data structures is called the Data Object REST API.
Manipulating Sentinel data objects allows an external program to affect Sentinel data and behavior. For example, new user accounts can be created using the Data Object REST API, or existing user accounts can be locked using the API.

Client-side Libraries

Sentinel provides a set of client-side libraries for Java and for GWT (Google Web Toolkit).
The client-side libraries allow a developer to list, read, create, update, and delete Sentinel data objects. The Sentinel data objects are presented in client Java or GWT code as data object beans. The bean instances are transferred between the client and the Sentinel server using bean transporters.

Data Object Beans

Data object beans are classes generated from internal Sentinel data object descriptions, and are similar to typical Java beans. Sentinel data object beans are fairly simple data containers with a getter and setter methods for data members.
Sentinel data objects are a collection of named data items (e.g., "Name") and named references to other data objects. Data object beans provide access to the named attributes and to the named relations.

Data Object Attributes

The named data items contained within a Sentinel data object are referred to as data object attributes. Each attribute has a data type, including:
Data object attribute types are represented in Java/GWT by appropriate language types (e.g., java.lang.String, long, java.util.Date, java.util.List, etc.).
A Data object attribute type that is a Sentinel Data object is presented as the appropriate bean type.

Data Object Relations

References to other data objects are presented as URLs. Depending on the type of reference, a reference may be a single URL or a collection of URLs.
The URLs representing referenced objects may be used with an appropriate bean transporter to get the beans containing the data object representations.

Bean Transporters

The beans are sent to and obtained from the Sentinel server using a bean transporter . The transporter serves to hide many of the messy details of the HTTP REST interface, allowing the developer to concentrate on the data itself, rather than the details for transporting the data.

TinyQ Filter Expressions

A list of Sentinel data objects of a particular type can be obtained using one of the transporter's list methods. The list results can be narrowed using a filter expression using a syntax referred to as TinyQ .
The TinyQ language is designed to be provide an efficient syntax for use with URLs and as such has a rather arcane syntax that is not very human-friendly. The TinyQBuilder utility class is provided for Java and GWT code to make creating filter expressions easier.
A filter expression narrows a list of data objects by selecting data objects with particular attribute values, or by selecting data objects with a relation to data objects that have particular values.
For example, to restrict the list of users to only that which has a username of "admin" a filter expression that specifies the user "name" attribute is equal to "admin" would be used as the query parameter to a user bean transporter's list method.
The TinyQ expression for the above example is "name.eadmin", and could be constructed using the following java code: 
String query = new TinyQBuilder().equal(UserBean.NAME, "admin").build();
Note that the TinyQ implementation used for the DataObject REST API performs all string comparisons in a case-insensitive manner.

Result Pages

A bean transporter returns the results of a call to its list methods as a collection of beans. The maximum size of the collection may be restricted when calling list using the pageSize parameter.
Additional "pages" of data may be obtained using URLs supplied in the result from the transporter's list method.

Restricting Returned Attributes

Sometimes it is desirable to restrict the amount of data returned from a server request (e.g., a listing of thousands of data objects when only the data objects' names are needed).
To accomplish this the transporter's list method allows the set of fields returned to be restricted. See the fields parameter on several of the list and get method overrides.

Synchronous versus Asynchronous Bean Transporters

In Java there exist both a synchronous implementation and an asynchronous implementation of the general bean transporter. (In GWT only an asynchronous model is supported because of the inherently asynchronous GWT HTTP support.)
The synchronous implementation is easier to use because methods are provided that return data and throw exceptions, whereas the asynchronous implementation methods use callbacks. The synchronous methods block the calling thread until the result from the server is obtained.
The asynchronous implementation should be used when higher performance or user responsiveness is needed. The transporter methods do not block the calling thread. The results of the server requests are reported via callback on a thread other than the calling thread.

Example Code

Examples of various Java operations with Sentinel data objects are found here.

Javadocs

The javadocs for the client code are found here.

Client Code Download

The client code .jar files may be downloaded using the following links:

HTTP

The URLs used to access each data object type within the DataObject REST API share syntax and semantics. There are four basic operations on an object: create, read, update, and delete (note that not every operation is applicable to every object type).
Operations that accept or return object data use JSON to represent the object data. Within the JSON representation references to other data objects are URLs.
The URLs all have the following syntax general syntax:
https://<host>:<port>/SentinelRESTServices/objects/<type>[/other stuff]

URL Syntax for Specific Operations

Create

HTTP POST
https://<host>:<port>/SentinelRESTServices/objects/<type>

Read (multiple objects)

HTTP GET
https://<host>:<port>/SentinelRESTServices/objects/<type>[?<filter and parameters>]

Read (count of objects)

HTTP GET
https://<host>:<port>/SentinelRESTServices/objects/<type>[?<filter>]

Read (single object)

HTTP GET
https://<host>:<port>/SentinelRESTServices/objects/<type>/<unique object identifier>

Update

HTTP PUT
https://<host>:<port>/SentinelRESTServices/objects/<type>/<unique object identifier>

Delete

HTTP DELETE
https://<host>:<port>/SentinelRESTServices/objects/<type>/<unique object identifier>