LabVantage REST Web Services

LabVantage REST Web Services allow client requests to be issued and executed using Web Services that are compliant with the REST architectural style for networked hypermedia applications. REST defines a formal set of constraints, as defined in http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm. LabVantage provides its own REST API that complies with these constraints as follows:

REST Constraint	Description of REST Constraint	LabVantage REST API Compliance
Client-Server	A uniform interface separates clients from servers. This separation of concerns means that, for example, clients are not concerned with data storage, which remains internal to each server, so that the portability of client code is improved. Servers are not concerned with the user interface or user state, so that servers can be simpler and more scalable. Servers and clients may also be replaced and developed independently, as long as the interface between them is not altered.	The LabVantage REST API makes no assumptions about the client implementation other than it must support the ability to submit and receive HTTP GET, PUT, POST and DELETE requests and the creation and interpretation of JSON string data. The API and resource URIs are agnostic to the data structures and implementation patterns in the LabVantage server application and database.
Stateless	The clientserver communication is further constrained by no client context being stored on the server between requests. Each request from any client contains all the information necessary to service the request, and session state is held in the client. The session state can be transferred by the server to another service such as a database to maintain a persistent state for a period and allow authentication. The client begins sending requests when it is ready to make the transition to a new state. While one or more requests are outstanding, the client is considered to be in transition. The representation of each application state contains links that may be used the next time the client chooses to initiate a new state-transition.	The LabVantage REST API assumes that each request is independent of the last and self-contained in its definition. However, each request (with a few exceptions) must contain a connection token (ConnectionId) that represents the LabVantage authentication of the request. See Creating a Connection for details.
Cacheable	As on the World Wide Web, clients and intermediaries can cache responses. Responses must therefore, implicitly or explicitly, define themselves as cacheable, or not, to prevent clients from reusing stale or inappropriate data in response to further requests. Well-managed caching partially or completely eliminates some clientserver interactions, further improving scalability and performance.	The LabVantage REST API caches responses where possible. However, due to the dynamic nature of the data, this is often impractical.
Layered System	A client cannot ordinarily tell whether it is connected directly to the end server, or to an intermediary along the way. Intermediary servers may improve system scalability by enabling load balancing and by providing shared caches. They may also enforce security policies.	The LabVantage REST API makes no assumptions about layers of hardware and/or software between the client and the server.
Code on Demand (optional)	Servers can temporarily extend or customize the functionality of a client by the transfer of executable code. Examples of this may include compiled components such as Java applets and client-side scripts such as JavaScript. "Code on demand" is the only optional constraint of the REST architecture.	The LabVantage REST API does not implement code on demand.
Uniform Interface	The uniform interface constraint is fundamental to the design of any REST service. The uniform interface simplifies and decouples the architecture, which enables each part to evolve independently. The four constraints for this uniform interface are:
	Identification of Resources Individual resources are identified in requests using URIs as resource identifiers. The resources themselves are conceptually separate from the representations that are returned to the client. For example, the server may send data from its database as HTML, XML or JSON, none of which are the server's internal representation.	See LabVantage REST API for request details. Additional request data and all server responses are sent using JSON representations.
	Manipulation of Resources through these Representations When a client holds a representation of a resource, including any metadata attached, it has enough information to modify or delete the resource.	See the LabVantage REST API for details of the JSON representation manipulation process through GET, POST, PUT and DELETE.
	Self-Descriptive Messages Each message includes enough information to describe how to process the message. For example, which parser to invoke may be specified by an Internet media type (previously known as a MIME type). Responses also explicitly indicate their cache-ability.	Each LabVantage REST API request is self-contained in its definition.
	Hypermedia as the Engine of Application State (HATEOAS) Clients make state transitions only through actions that are dynamically identified within hypermedia by the server (e.g., by hyperlinks within hypertext). Except for simple fixed entry points to the application, a client does not assume that any particular action is available for any particular resources beyond those described in representations previously received from the server.	The LabVantage REST API does not currently implement HATEOAS.

Terminology

The LabVantage REST API follows the standardized patterns and conventions described using the LabVantage terminology below.

Resources

"Resources" identify the LabVantage entities that are exposed in the REST API. Generally, these are SDCs (such as Samples). Resources are defined in the RESTPolicy.

Collections

"Collections" are arrays of resources (such as a collection of Samples) that are often generated as a result of a resource request, but may be manually created for updating resources.

Endpoints

"Endpoints" are the URLs that represent the resources, collections, sub-resources and sub-resource collections that are defined in the RESTPolicy. For example, /rest/sdc/samples/S1 represents the Sample S1, whereas /rest/sdc/samples?queryid=TodaysSamples represents the collection of Samples for today.

•

"System endpoints" define a basic set of resources for checking to determine if the REST API is operational and accessing the built-in API documentation, establishing connection with the REST API, and finding/executing LabVantage System Actions.

•

"SDC endpoints" provide access to SDC data using HTTP methods and LabVantage Actions. SDC endpoints are defined using the RESTPolicy. The RESTPolicy contains several OOB endpoints defined for entities such as Samples, Sample Tests, Sample Data Sets, Sample Data Items, etc. Additional SDC endpoints can also be defined. An SDC Resource can point to a "Primary Resource" or a "Sub Resource":

•	A "Primary Resource" is an SDC or sub-classed SDC, the latter queried using a restrictive where to restrict the type of Primary Resource exposed (such as only a "QC" Sample Type).
•	A "Sub Resource" defines the details linked to an SDC (such as Tests, Data Sets, Data Items, detail tables, etc.). Sub Resources are defined in the same manner as Primary Resources, but can be used only in conjunction with Primary Resources. Sub Resources cannot be requested independently of a Primary Resource. A Primary Resource will have a defined set of Sub Resources that can be accessed. Sub Resources can also be represented as collections.
•	A "Reverse FK Sub Resource" is a specialized Sub Resource that is used to define reverse foreign-key relationships (such as Batch Samples).

HTTP Methods

HTTP methods identify the type of request being sent to the API as described below. The term "generally used for" is applied to POST, PUT and DELETE methods, as the methods are mapped to LabVantage System Actions that may not exactly create, update or delete data. For example, a DELETE method on a Sample may mark the Sample as deleted rather than actually deleting it. These mappings are defined in the RESTPolicy.

•	GET is used for retrieving data (such as "get the list (collection) of Samples created today").
•	POST is generally used for creating data (such as "create a new Sample with the following column values"). POST sends data to the server to add a Primary or Sub Resource and returns a JSON object containing a collection/array of the resource data created along with a definition of the Action call made.
•	PUT is generally used for updating data (such as "update the Sample description"). PUT sends data to the server to update a primary or sub-resource. When PUTting data to the root resource, the PUT data must contain a collection of keys and data values identified with the resource path for the resource that requires modification (see Sample example below). Multiple PUT methods can be added to the root resource request to define a set of potential Actions that can be performed on a resource.
•	DELETE is generally used for deleting data (such as "delete a Sample").

HTTP methods may be applied to Primary Resources and Sub Resources (such as "get the list (collection) of Tests for a Sample", "add a Test to a Sample", "update a Sample Test" and "delete a Sample Test").

Resource Root and Resource Id

Resource requests to SDC endpoints are made to either the "Resource Root" or a specific "Resource Id". These are defined in the RESTPolicy.

Requests to the "Resource Root" can be used for primary SDC data or Sub Resource data. For example:

•

/rest/sdc/samples

This is a Resource Root request to the samples resource.

GET typically returns a collection of Samples.

POST typically creates a new Sample.

PUT typically updates a collection of Samples.

DELETE is not supported.

•

/rest/sdc/samples/S1/tests

This is a Resource Root request on the sampletests resource.

GET typically returns a collection of Tests for a Sample.

POST typically creates a new Test on a Sample.

PUT typically updates a collection of Tests for a Sample.

Requests to the "Resource Id" can be used for detail SDC data or a specific Sub Resource. For example:

•

/rest/sdc/samples/S1

This is a Resource Id request to the samples resource.

GET typically returns details about a Sample.

POST is not supported.

PUT typically updates a single Sample.

DELETE typically deletes a single Sample.

•

/rest/sdc/samples/S1/tests/MoistureAnalysis

This is a Resource Id request on the sampletests resource.

GET typically returns details about a Test on a Sample.

POST is not supported.

PUT typically updates a single Test on a Sample.

DELETE typically deletes a single Test from a Sample.

The RESTPolicy defines separate sets of rules for Resource Root requests and Resource Id requests, defining the action to be taken for each of the HTTP methods.

JSON

JSON is used to represent the request and response data. Certain HTTP requests require JSON data to be added to the request body. For example, when POSTing to a Sample endpoint, the JSON data may represent the Sample column values to be added. All responses contain a string representation of a JSON object, which contains (as a minimum) the HTTP status and code of the request. Additional data is added on a per-request basis. Invalid requests will return a JSON object with the appropriate error details.

Security

The REST API is open to the Web and HTTP requests. Therefore, security is paramount. Accordingly, REST services should be run over an HTTPS (SSL/TLS) connector as a basic level of security. In addition, the LabVantage SecurityPolicy provides a variety of security measures to protect unsolicited and malicious requests. These include (but are not limited to):

•	The REST API can be enabled/disabled.
•	The HTTPS (SSL/TLS) restriction can be overridden.
•	REST API Action processing can be restricted.
•	The Session Management options "Session Binding", "Allow ConnectionId In Request", "Encrypt ConnectionId", and "Dedicated ConnectionId" apply to REST services.

Additional security control is provided in the RESTPolicy. For example, requests to Resources and Sub Resources can be enabled/disabled.

Client Tools

REST is an HTTP client API. As such, it has no traditional UI. Various tools exist to test REST APIs, such as Postman (available at www.getpostman.com and the Google App Store), which is used to generate the examples in this documentation. Alternatively, you can write your own client application (Java Public API class sapphire.servlet.RestClient is provided to help you do this).

LabVantage REST API

Top

SecurityPolicy and RESTPolicy

In order to issue requests using the LabVantage REST API, you must enable and configure the desired functionality in the SecurityPolicy (REST Services section) and the RESTPolicy. In addition to those highlighted in the Security overview, these Policies contain many interactive settings. You must therefore familiarize yourself with all of those Policy options, then enable/configure the Policies according to your security requirements and functional needs.

At a minimum:

•	In SecurityPolicy → REST Services, enable the REST service and setup all other properties as desired.
•	In RESTPolicy → System Resources and RESTPolicy → SDC Resources, enable the resources you will be using.

Creating a Connection

All requests require a valid ConnectionId to execute. You must therefore create a ConnectionId at the beginning of your session. When using a client tool (such as Postman), you can do this by calling POST /rest/connections, and passing the databaseid, username and password with the request as body data (see the Example of POST /rest/connections). This will create a ConnectionId and return it. It will also add the ConnectionId as a cookie, which you can see in the returned header data. For the duration of the session, each subsequent request (until you close the client) will have the cookie sent to the server to authenticate the request. Note that a ConnectionId cannot be passed in the body data.

In general, there are three ways a ConnectionId can be passed with a request:

•	As a cookie. This is the technique previously discussed by calling POST /rest/connections.
•	As an Authenticate token in the header. This may be the desired technique for automated processes.
•	As a query parameter in the URL. However, this is subject to rejection if the SecurityPolicy setting "Session Management → Allow ConnectionId in Request" is set to No.

It is worth mentioning that there are only two requests that can execute without a ConnectionId: GET /rest and POST /rest/connections. These use a DatabaseId that is passed into the request. They are not generally used.

Built-In API Documentation

Online documentation for the LabVantage REST API can be accessed by issuing a URL request to /rest/api. If labvantagedoc.war is deployed, this documentation can also be accessed through the "Help" icon in the application, but only if the User has the Role specified by the "REST API Role" property in the helpgizmo. The REST documentation shows the APIs for only the resources you have enabled in the RESTPolicy.

Examples

Here are some examples to demonstrate requests that act on Connections, Actions, and SDCs.

Connections

POST /rest/connections

This example creates and returns a new ConnectionId.

PUT /rest/connections/{connectionid}

This example pings a ConnectionId.

GET /rest/connections/{connectionid}

This example checks if a ConnectionId is valid.

DELETE /rest/connections/{connectionid}

This example clears a ConnectionId.

Actions

GET /rest/actions

This example returns the set of Actions that can be used in the REST API.

GET /rest/actions/{actionid}

This example returns the properties for the specified Action.

POST /rest/actions

This example executes an Action Block defined in the request body.

POST /rest/actions/{actionid}

This example executes the specified Action using the properties defined in the request body.

SDCs

For SDC Resources in general, returned columns are defined in the RESTPolicy.

Here we have three examples that demonstrate selectivity on the same basic request.

GET /rest/sdc/samples?queryid={queryid}

Retrieves and returns a list of Sample details using a LabVantage Query with no params specified.

GET /rest/sdc/samples?queryid={queryid}&param1={param}

Retrieves and returns a list of Sample details using a LabVantage Query and params defined in the request.

GET /rest/sdc/samples?keyid1={keyid1}

Retrieves and returns a list of Sample details using a defined key list.

GET /rest/sdc/samples/{sampleid}

Retrieves and returns details for a single Sample.

POST /rest/sdc/samples

Adds a new Sample using the details/properties posted in the request body and returns the Sample properties.

PUT/rest/sdc/samples/{sampleid}

Updates a single Sample using the details/properties posted in the request body, and returns the Sample properties.

DELETE /rest/sdc/samples/{sampleid}

Deletes a single Sample and returns the deleted SampleId.

GET /rest/sdc/samples/{sampleid}/tests

Retrieves the list of Tests for a Sample.

POST /rest/sdc/samples/{sampleid}/tests

Adds one or more Tests to a specified Sample using the details posted in the request body, and returns the Tests added.

PUT /rest/sdc/samples/{sampleid}/tests

Updates Test details for a specified Sample using the details posted in the request body, and returns the edited Test details.

PUT /rest/sdc/samples/{sampleid}/tests/{testid}

Updates details for a specified Sample Test using the details posted in the request body, and returns the edited Test details.

PUT /rest/sdc/samples/{sampleid}/tests/{testid}?action={methodqualifier}

Executes the Test action for the Sample for the PUT method (qualified by the specified action) using details posted in the request body. In this example, the action method qualifier is cancel, so it will cancel the Test.

DELETE /rest/sdc/samples/{sampleid}/tests/{testid}

Deletes the specified Test from the specified Sample and returns a confirmation.

HTTPS

Top

For guidelines concerning use of REST Web Services over HTTPS connections, see Guidelines for Using Web Services over HTTPS.