Introduction
REST Data Access Web Service Reference Specification
Page Contents
A summary of specific versions, resources, and XML namespaces is provided below.
- Supported Versions
- Changes in Current Revision
- Requesting an API Version
- REST
- API Data Types
- XML Data Elements
- XML Data Types
The REST Data Access Web Service is the fundamental interface in the GenoLogics Rapid Scripting API. Data is provided in XML with data access methods via HTTP.
*REST* (Representational State Transfer) is an architectural design style, not a specification. The term REST was incorporated into the API's name because the RESTful design style is perfect for research lab data access: self-descriptive, self-contained data representation in formats widely applicable to general scripting languages and the internet.
This REST reference section contains specifics and details on each resource, supported methods, and XML elements. For details on any resource click on the *REST resources* tree view at the left of this page. For details on the XML used by each resource method, use the *XML Namespaces* tree view.
A good place to start is in the [General Concepts - REST API|REST:General Concepts - REST API] section. You should also be familiar with the [Prerequisites|TOP:Prerequisites] and [TOP:Key Concepts] sections. To help navigate the resources, the following diagram highlights the methods available and the major resource relationships.
{gallery:include=REST Resource Map v2r16.jpg}Supported Versions
API changes are tracked with the combination of a version number and a revision number.
The version number indicates forwards and backwards compatibility, while the revision number within the version describes features added to the API that will not negatively affect current functionality. Only the version number is referenced as part of the request; the revision number simply tracks incremental enhancements to the API.
The following version is described in this section of the web site:
| Version | Current Revision | Released with |
|---|---|---|
| v2 | r16 | Clarity LIMS 2.1 |
For details on previous versions, see the [Previous REST Versions|REST:Previous REST Versions] page.
----Changes in Current Revision
* Multiple permitted reagent categories in step configuration* Reagents endpoint shows selected reagent category for the step and validates against it
* Placements endpoint shows selected containers for the step
* Email is a required field when creating/updating researchers
* Process execution accounts for fixed number of outputs to generate for per-reagent-label output types
----
Requesting an API Version
The version number is a path parameter in each resource URI in the API. The desired API version is substituted into the following request URI:
/\{version\}/\{resource\}
The following example would request version 2 of the containers resource:
- /v2/containers
REST
This API supports a Representational State Transfer (REST) model for accessing a set of resources through a fixed set of operations. The following resources are accessible through the RESTful model:
- /{version}
- /{version}/artifactgroups
- /{version}/artifactgroups/{experimentid}
- /{version}/artifacts
- /{version}/artifacts/{limsid}
- /{version}/artifacts/batch/retrieve
- /{version}/artifacts/batch/update
- /{version}/configuration/protocols
- /{version}/configuration/protocols/{protocolid}
- /{version}/configuration/protocols/{protocolId}/steps/{stepId}
- /{version}/configuration/udfs
- /{version}/configuration/udfs/{udfid}
- /{version}/configuration/udts
- /{version}/configuration/udts/{udtid}
- /{version}/configuration/workflows
- /{version}/configuration/workflows/{workflowid}
- /{version}/configuration/workflows/{workflowid}/stages/{stageid}
- /{version}/containers
- /{version}/containers/{limsid}
- /{version}/containers/batch/create
- /{version}/containers/batch/retrieve
- /{version}/containers/batch/update
- /{version}/containertypes
- /{version}/containertypes/{containertypeid}
- /{version}/controltypes
- /{version}/controltypes/{controltypeid}
- /{version}/external/{externalid}
- /{version}/files
- /{version}/files/{limsid}
- /{version}/glsstorage
- /{version}/instruments
- /{version}/instruments/{instrumentid}
- /{version}/labs
- /{version}/labs/{labid}
- /{version}/processes
- /{version}/processes/{limsid}
- /{version}/processtemplates
- /{version}/processtemplates/{limsid}
- /{version}/processtypes
- /{version}/processtypes/{processtypeid}
- /{version}/processtypes/{processtypeid}/fields/{fieldid}
- /{version}/processtypes/{processtypeid}/types/{typeid}
- /{version}/processtypes/{processtypeid}/types/{typeid}/fields/{fieldid}
- /{version}/projects
- /{version}/projects/{limsid}
- /{version}/reagenttypes
- /{version}/reagenttypes/{reagenttypeid}
- /{version}/researchers
- /{version}/researchers/{researcherid}
- /{version}/route/artifacts
- /{version}/samples
- /{version}/samples/{limsid}
- /{version}/steps/{limsid}
- /{version}/steps/{limsid}/actions
- /{version}/steps/{limsid}/placements
- /{version}/steps/{limsid}/pools
- /{version}/steps/{limsid}/programstatus
- /{version}/steps/{limsid}/reagents
There is also a WADL document describing the REST API.
API Data Types
All endpoints act on a common set of data. The data can be represented in different data formats (i.e. MIME types), depending on the endpoint that consumes and/or produces the data. The data can described by XML Schema, which definitively describes the XML representation of the data, but is also useful for describing the other formats of the data, such as JSON.
This document will describe the data using terms based on XML Schema. Data can be grouped by namespace, with a schema document describing the elements and types of the namespace. Generally speaking, types define the structure of the data and elements are instances of a type. For example, elements are usually produced by (or consumed by) a REST endpoint, and the structure of each element is described by its type.
API Data Type Schemas
| id | namespace | schema file |
|---|---|---|
| ri | http://genologics.com/ri | ri.xsd |
| art | http://genologics.com/ri/artifact | artifact.xsd |
| artgr | http://genologics.com/ri/artifactgroup | artifactgroup.xsd |
| cnf | http://genologics.com/ri/configuration | configuration.xsd |
| con | http://genologics.com/ri/container | container.xsd |
| ctp | http://genologics.com/ri/containertype | containertype.xsd |
| ctrltp | http://genologics.com/ri/controltype | controltype.xsd |
| exc | http://genologics.com/ri/exception | exception.xsd |
| file | http://genologics.com/ri/file | file.xsd |
| inst | http://genologics.com/ri/instrument | instrument.xsd |
| lab | http://genologics.com/ri/lab | lab.xsd |
| prc | http://genologics.com/ri/process | process.xsd |
| prx | http://genologics.com/ri/processexecution | processexecution.xsd |
| ptm | http://genologics.com/ri/processtemplate | processtemplate.xsd |
| ptp | http://genologics.com/ri/processtype | processtype.xsd |
| prj | http://genologics.com/ri/project | project.xsd |
| prop | http://genologics.com/ri/property | property.xsd |
| protcnf | http://genologics.com/ri/protocolconfiguration | protcnf.xsd |
| rtp | http://genologics.com/ri/reagenttype | reagenttype.xsd |
| res | http://genologics.com/ri/researcher | researcher.xsd |
| rt | http://genologics.com/ri/routing | routing.xsd |
| smp | http://genologics.com/ri/sample | sample.xsd |
| stg | http://genologics.com/ri/stage | stage.xsd |
| stp | http://genologics.com/ri/step | step.xsd |
| protstepcnf | http://genologics.com/ri/stepconfiguration | protstepcnf.xsd |
| udf | http://genologics.com/ri/userdefined | userdefined.xsd |
| ver | http://genologics.com/ri/version | ver.xsd |
| wkfcnf | http://genologics.com/ri/workflowconfiguration | wkfcnf.xsd |
XML Data Elements
- namespace ri
- namespace art
- namespace artgr
- namespace cnf
- namespace con
- namespace ctp
- namespace ctrltp
- namespace exc
- namespace file
- namespace inst
- namespace lab
- namespace prc
- namespace prx
- namespace ptm
- namespace ptp
- namespace prj
- namespace prop
- namespace protcnf
- namespace rtp
- namespace res
- namespace rt
- namespace smp
- namespace stg
- namespace stp
- namespace protstepcnf
- namespace ver
- namespace wkfcnf
XML Data Types
- namespace ri
- namespace art
- namespace artgr
- namespace cnf
- namespace con
- namespace ctp
- namespace ctrltp
- namespace exc
- namespace file
- namespace inst
- namespace lab
- namespace prc
- namespace prx
- namespace ptm
- namespace ptp
- namespace prj
- namespace prop
- namespace protcnf
- namespace rtp
- namespace res
- namespace rt
- namespace smp
- namespace stg
- namespace stp
- namespace protstepcnf
- namespace udf
- namespace ver
- namespace wkfcnf