REST Web Services

Representational State Transfer (REST) is a style of software architecture for distributed information retrieval systems, most commonly observed by using the web.

•

REST governs proper behavior. It is not a methodology or a design principal, but rather a set of rules to which a system should conform.

•

REST allows a uniform interface between clients and servers that is simple and decoupled, enabling each system to evolve independently.

•

REST is referred to as stateless because each new API request contains all the information required to complete it without relying on previous requests. Conforming to these REST principals is referred to as being RESTful.

•

REST was developed in parallel with HTTP and makes use of this protocol. It is an elegant way to programmatically access resources over HTTP. It is flexible because you can use it with any language or tool that supports HTTP.

The web is probably the largest known RESTful system. Its behavior is simple:

1.

When selecting a link in a web browser, the system requests information by sending a GET request to the specified URL. This URL is a resource.

2.

The server that hosts the URL responds, typically with one of two things:

•

If the page exists, the server sends the browser an HTTP 200 response code and the contents of the page.

•

If the page does not exist, the server sends an HTTP 404 response code and an error message indicating that the page cannot be found.

Many software development groups use RESTful APIs. Google, Yahoo, and many public websites use the RESTful model for information access.

The REST API allows you to retrieve and update information using HTTP operations. This ability provides some flexibility in how to communicate with the system.

While REST requests and responses can be in various formats, we chose XML. Each resource and XML element is detailed in the REST API Documentation.

To use the REST API, sign in using HTTP BASIC authentication. The method used to authenticate depends on how you use the API:

•

When using a browser to retrieve information from the API, sign in to the browser with a user name and password. When signing in using a browser, the session remains open until the browser is closed.

•

When using an HTTP request tool to retrieve, add, update, or remove data using the API, the tool asks for a user name and password each time you submit a request to the system.

•

When using a script to communicate with the API, the script must first authenticate with the API. The session remains open for as long as the script is being actively read by the system.

The account you use to sign in to the API must have System Administrator or Facility Administrator privileges.

The API allows self-discovery of an object. When you request information about an object, the system typically returns URIs to its children and, sometimes, its parent. Use one URI to find the next URI in a hierarchy.

When viewing XML in a browser, tools can automatically create links from the URIs returned by the system. Examples of such tools are the Firefox Text Link or Linkificator add-ons. This way, you can select URIs to browse through the API.

Requests are made to the API by sending XML in HTTP calls:

•

GET is used to read an item.

•

POST to create an item.

•

DELETE to delete an item.

•

PUT is used to update an item.

In its simplest form, use a browser to enter and read the content of a URI, which allows browsing through the system. When using this method, a GET request is issued to the API for a specified object (referred to as a resource). The request returns XML containing the metadata about that resource. See the following section for details.

If you want to add, update, and delete small amounts of data using the API, use an HTTP request tool, such as the Firefox RESTClient add-on.

When working with REST, there are references to resources and namespaces.

For references:

A RESTful API groups related information into resources, each of which is referenced with a global identifier (URI).

In the API, for example, every sample in the LIMS has a resource for its information. When scripting, the resource is created or updated with POST and PUT HTTP calls. There are two types of resources: single and list types.

•

A list resource is used to access a collection of single resources (such as a listing of all samples).

•

The single resource type is used to access details on just one resource (a sample, for example).

It's important to understand how the information in the LIMS has been grouped and structured into resources. To learn more, see Structure of REST Resources.

For namespaces:

An API that uses XML relies on namespaces. In XML, namespaces define the vocabulary of elements and attributes in an XML document. Each REST resource references the XML structure defined by a particular namespace.

When scripting, we use namespaces to look up specific details related to the XML data elements, attributes, and formats that represent a resource. Namespaces also order the subelements of the XML document.

In the current revisions of the API, the PUT and POST methods read the subelements of the XML independent of order, but the namespace still defines the order of the XML provided in GET calls.

For sophisticated write operations and automation of work, you must use a script to communicate with the API. The About the Cookbook contains examples that demonstrate how to use scripts to perform your work.