REST General Concepts
REST and automation are the key interfaces for scripting. A language-agnostic application programming interface (API) is important to scientists as it allows for broad and diverse integration. Together, REST and automation provide powerful and easy-to-use scripting. However, you first need to understand the conceptual structure and design of these interfaces.
Within the Clarity LIMS Rapid Scripting API, REST technology is used to provide data specifically structured for life science research.
The API documentation includes the terms External Program Integration Plug-in (EPP) and EPP node.
As of BaseSpace Clarity LIMS v5.0, these terms are deprecated. The term EPP has been replaced with automation. EPP node is referred to as the Automation Worker or Automation Worker node. These components are used to trigger and run scripts, typically after lab activities are recorded in the LIMS.
If you are new to the REST Web Service, we recommend that you read Development Prerequisites and REST Web Services.
REST: A Web Service for Data Access
The REST Web Service is the fundamental data access interface using XML over HTTP. It is agnostic to programming languages as most languages support HTTP and XML with libraries or built-in methods.
In life science research labs, tracking samples and the data associated with biology, research, and lab work is complex. The REST resources return information that is human-readable and interpretable. Use a web browser to explore the XML returned.
REST represents real laboratory items and activities in self-contained groups of data called resources. It provides access to recorded lab steps and to sample test results, and it provides this access using resources. For example:
| • | The process and steps resources track the steps in the lab in terms of who did what and when. |
| • | The sample and artifact resources contain information on the submitted sample and test results on sample derivatives (also referred to as derived samples). |
The REST resources and their relationships are explained in Structure of REST Resources.
For full details of each resource, see the API Portal.
General Concepts
Requests are made to the API by sending XML messages:
| • | POST is used to create an item. |
| • | GET is used to read an item. |
| • | PUT is used to update an item. |
| • | DELETE is used to delete an item. |
HEAD requests are not supported.
The full URL to which requests should be sent varies depending on the specific installation, but it generally follows this format:
http[s]://<hostname>:<port>/api/<version.of.api>
Automation/EPP: GUI Trigger for Calling Scripts
Automation/EPP is used to trigger scripts from within the Clarity LIMS interface.
Script triggering is often used because the data collected needs to be dispatched for further processing. Automating data processing and returning information to the lab for immediate use, in the appropriate format, increases efficiency and quality.
File handling and file management are fundamental elements in life science scripting. When triggered, scripts can issue a command, transfer files for processing, and collect and transfer files back to the server. To enable triggering of scripts in any programming language, the information and files are provided for batch processing at the operating system command-line level.
For BaseSpace Clarity LIMS (earlier than v5):
To use automation, administrators complete the following steps.
| 1. | Create and configure master steps/processes with automations/EPP. |
| 2. | Write scripts that are triggered by these automations/EPP. |
| 3. | In the Clarity LIMS web interface, use the configured master steps/processes as building blocks to create and configure steps to be run by lab scientists. |
For BaseSpace Clarity LIMS (v5 and later):
As of Clarity LIMS v5, the Operations Interface Java client, which was used by administrators to configure processes, consumables, user-defined fields, and users, has been deprecated. All configuration and administration tasks are now executed in the Clarity LIMS web interface.
To use automation, administrators complete the following steps.
| 1. | In Clarity LIMS, create and configure master steps. |
| 2. | Configure automations that trigger scripts. Enable those automations on the master steps. |
| 3. | Use the configured master steps as building blocks to create and configure steps to be run by lab scientists. |
