Purpose & Features of the Sample API¶
Purpose¶
The purpose of the MAVE Sample API is to provide a single, stable interface for retrieving sample metadata from the Multi LIMS Warehouse (MLWH).
Without the Sample API, downstream consumers would need to connect directly to MLWH, understand its schema, write their own parameterised SQL queries, handle pagination, and normalise the results. The Sample API encapsulates all of that behind a simple GET /mave/sample/v1 call.
The Sample API is designed to:
- Retrieve sample data associated with one or more sequencing run IDs
- Provide a standardised API interface over MLWH
- Abstract database-specific query logic
- Support downstream MAVE QC workflows
- Return harmonised sample metadata in JSON format
Data Retrieved¶
The API retrieves and combines data from several MLWH tables to produce a harmonised record per sample.
| Data Area | Description |
|---|---|
| Sample Metadata | Sample name and supplier name |
| Study Information | Study identifiers |
| Sequencing Metadata | Run ID, lane, paired read indicator, sequencing technology |
| Storage Information | iRODS root collection and relative file path |
Key Features¶
Multi-Run Support¶
The API accepts a comma-separated list of run IDs in a single request, returning results for all supplied runs in one response. This avoids the need for consumers to make multiple sequential calls when working with several runs.
Pagination¶
The API supports limit and offset query parameters, allowing consumers to page through large result sets efficiently. Default values are applied if pagination parameters are omitted.
Parameterised Query Safety¶
All SQL queries executed against MLWH use parameterised inputs. This prevents SQL injection and ensures safe handling of consumer-supplied run ID values.
Harmonised Response Shape¶
The response uses a consistent JSON structure regardless of how many run IDs are supplied or how many samples are returned. Each sample object contains the same set of fields, with null used for any fields not available in MLWH.
Observability¶
All responses include correlation and trace identifiers in headers to support debugging, tracing, and operational monitoring. Structured logging and distributed tracing are enabled across all API layers.