Skip to content

MAVE Sample API: User Guide

This user guide covers the following topics regarding the Sample API provided by the MAVE platform:

  1. The purpose of the Sample API: Explains what the API provides and why it exists.
  2. How the API works: Describes how the API retrieves and harmonises sample data from MLWH.
  3. How to use the Sample API: Covers the endpoint, request parameters, response structure, and error codes.
  4. Example response: Provides a concrete response example.

The purpose of this document is to give consumers an overview of the Sample API and what it is designed to achieve. It does not explore the detailed technical implementation of the underlying MLWH integration. If you need more details, please contact the MAVE team.

Overview

The MAVE Sample API provides a standardised interface for retrieving sample metadata from the Multi LIMS Warehouse (MLWH).

The API allows consumers to retrieve all sample records associated with one or more sequencing run IDs.

The API abstracts the underlying MLWH database structure and returns a harmonised JSON response suitable for downstream MAVE QC and processing workflows.

Nomenclature

Before reading the rest of the documentation, it is useful to be familiar with the following terms.

  • MLWH (Multi LIMS Warehouse): The Multi LIMS Warehouse is a centralised data store that holds sample, study, and sequencing metadata generated across LIMS systems at the Wellcome Sanger Institute.
  • Run ID: A numeric identifier for a sequencing run. Multiple samples may be associated with a single run ID across different lanes.
  • Sample: A biological specimen processed for sequencing. Each sample record in MLWH carries metadata such as name, supplier name, study, and sequencing location.
  • iRODS: The Integrated Rule-Oriented Data System — the storage infrastructure used at Sanger for sequencing data. The Sample API returns iRODS path information for each sample.
  • Pagination: The API supports limit and offset parameters to control how many records are returned in a single response and at what position in the result set to start.