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:
- string
- number
- date
- data object
- list
- set
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
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>