REST API

Introduction

REST Data Access Web Service Reference Specification

Page Contents

A summary of specific versions, resources, and XML namespaces is provided below.

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 REST General Concepts section. To help navigate the resources, the following diagram highlights the methods available and the major resource relationships.

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 r26 Clarity LIMS 5.1

Previous versions can be accessed like so: http://genologics.com/developer/{ClarityVersion}

For example: http://genologics.com/developer/4.2

----

Changes in Current Revision

  • Demux endpoint has been added for individual artifacts: /api/v2/artifacts/{limsid}/demux
  • Added LIST/GET endpoints for step automations:
    • /api/v2/configuration/automations
    • /api/v2/configuration/automations/{id}
  • Added Pre-release POST/PUT endpoints for step automations:
    • /api/v2/configuration/automations
    • /api/v2/configuration/automations/{id}
  • Automations can have files attached to them. The files endpoint will accept an automation uri as a valid attach-to entity.
  • Removed ability to update the attach-to attribute of a file on PUT.
  • Added 'original-name' element to the file resource.
  • Added 'automationname' and 'originalname' parameters to the file LIST endpoint.
  • PUT/POST on processtype with a process parameter (step automation) has changed behaviour:
    • Will attempt to reuse existing identical automations before creating a new one.
    • It will no longer be possible to change the details of an existing automation.
    • Automation can now be specified via uri.
  • We have deprecated the custom fields on process-type's process-output elements.
    • These fields are no longer honored when running steps in Clarity or using the steps API – all of the output's custom fields can be written.
    • However, the output's field associations will continue to be honored when using the processes API.
  • Added DELETE to sample: /api/v2/samples/{limsid}

----

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:

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
aut http://genologics.com/ri/automation aut.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
itp http://genologics.com/ri/instrumenttype instrumenttype.xsd
lab http://genologics.com/ri/lab lab.xsd
perm http://genologics.com/ri/permission permission.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
que http://genologics.com/ri/queue queue.xsd
kit http://genologics.com/ri/reagentkit reagentkit.xsd
lot http://genologics.com/ri/reagentlot reagentlot.xsd
rtp http://genologics.com/ri/reagenttype reagenttype.xsd
res http://genologics.com/ri/researcher researcher.xsd
role http://genologics.com/ri/role role.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

XML Data Types

Home

REST Endpoints

XML Data Elements

XML Data Types

© Copyright 2018 GenoLogics Life Sciences Software, An Illumina Company.
Generated by Enunciate. Template design by Arcsin.