Mercian - Api-v1

The labPortal REST API allows you to interact with labPortal data.

Since the API is based on REST principles, it's very easy to write and test applications. You can use your browser to access URLs, and you can use pretty much any HTTP client in any programming language to interact with the API. The API Supports Swagger and there is a Swagger Test UI available.

Base URL

All URLs referenced in the documentation have the following base:

https://mercian.labportal.co.uk/api-v1

The labPortal REST API is served over HTTPS. To ensure data privacy, unencrypted HTTP is not supported on the production instance of labPortal.

During testing you can use the test instance of labPortal, however HTTPS is disabled for all test environments

http://test.mercian.labportal.co.uk/api-v1

Credentials

All requests to labPortal's REST API require you to authenticate using HTTP basic auth to convey your identity. The username is your email that you used to register on labPortal. The password is your labPortal password.

Most HTTP clients (including web-browsers) present a dialog or prompt for you to provide a username and password for HTTP basic auth.

If you are going to be calling labPortal's REST API from an application which you would like to embed the username and password within, then you will be required to set the authentication headers of the HTTP request manually.

To do this you will need to:

Base 64 encode the email and password as a concatenated string
email:password
Set the Authorization Http Header, as follows
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

Response Formats

The labPortal REST API returns JSON formatted messages by default. To return XML messages you will have to add an Accept HTTP header to your request

Accept: application/xml

Test Requests

A simple get request can be tested directly in the browser.

Document

Document Controller is used to Upload documents to labPortal

API	Description
POST api-v1/library/documents	Uploads the posted document to labPortal
GET api-v1/library/documents/{id}	Returns a DocumentMessage (details about the document and a download link) for the document with the given Id

Job

The Results Job Resource represents Jobs that can be uploaded or downloaded from labPortal

API	Description
GET api-v1/results/job?pageNumber={pageNumber}&pageSize={pageSize}	Return all Jobs, paginated by and
GET api-v1/results/job/{id}	Return job with labPortal Id
GET api-v1/results/job?limsid={limsid}	Return job with LIMS Id
DELETE api-v1/results/job/{id}	Delete Job with labPortal id
POST api-v1/results/job/{id}/attachment	Attachment, When documents have been uploaded to labPortal the Job record can be marked with an attachment so that the user can query for the documents Use this api to update the attachment attribute of a Job The body must container a Multipart Form data with the content as: attachment=true
POST api-v1/results/job	Post a new or existing job, if job does not exist you will receive a HttpCreated, else the job will be updated and the response will be HttpOk Jobs use the property LimsId, to check for existence

Cache

Controller responsible for the results cache

API	Description
POST api-v1/results/cache/clear	If called from an Azure application, clears the reference data cache and returns HTTP 204 (Success, no content), otherwise does nothing and returns HTTP 400 (Bad Request)

OrderSchema

Methods for retrieving information about order schemas for use in the public API

API	Description
GET api-v1/commerce/orderschema	Returns a list of all order schemas the current user has access to
GET api-v1/commerce/orderschema?id={id}	Returns detailed information about the order schema with the specified Id
GET api-v1/commerce/orderschema/users	Returns an array containing the email address of all users who can access an order schema, and the IDs of the order schemas they can access

Order

Allows the retrieval of orders from labPortal

API	Description
GET api-v1/commerce/orders/{id}	Get an order by the order id
GET api-v1/commerce/orders/{status}	Get an order by order status
POST api-v1/commerce/orders/submitted	Marks the order specified by Id within the post body as submitted (downloaded and imported into a laboratory LIMS system)
GET api-v1/commerce/orders/version	Returns the numeric version number of the active orders system, or -1 if there isn't one

Sample

Results-Sample Resource Represents a labPortal sample, properties and nested results and result metadata

API	Description
GET api-v1/results/sample/{id}	This is the basic request to get a Sample representation.
GET api-v1/results/sample?limsid={limsid}	This is the basic request to get a Sample representation. The message format
GET api-v1/results/sample?property={property}&value={value}&pageNumber={pageNumber}&pageSize={pageSize}	A basic search function to retrieve samples. Supports pagination so that large datasets can be traversed. Samples returned in the order that they have been uploaded to labPortal. Therefore the first sample will be the most recently updated Sample.
GET api-v1/results/sample?searchId={searchId}&pageNumber={pageNumber}&pageSize={pageSize}&grid={grid}	Returns a list of Samples based on a Saved Search
POST api-v1/results/sample/{id}/attachment	Attachment, When documents have been uploaded to labPortal the Sample record can be marked with an attachment so that the user can query for the documents Use this api to update the attachment attribute of a sample The body must container a Multipart Form data with the content as: attachment=true

Search

The API which calls the jobs and samples re-indexing services

API	Description
GET api-v1/search/Index	Tells the job indexing service to re-index the jobs
GET api-v1/search/ReIndexSamples	Tells the sample indexing service to re-index the samples
GET api-v1/search/ForceReIndexSamples	Tells the sample indexing service to perform a full re-index of the samples