How the Sample API Works¶

The API retrieves sample data from the Multi LIMS Warehouse (MLWH) using the supplied run ID(s) and returns a harmonised JSON response.

Processing Steps¶

Step 1 – Request Validation¶

The API validates the incoming request parameters.

• The run_ids parameter is required. If missing, a 400 Bad Request error is returned.
• limit and offset are optional integers. Default values are applied if omitted.

Step 2 – Run ID Normalisation¶

The supplied run_ids string is parsed and normalised into a list of discrete run ID values. Whitespace is trimmed and values are validated before the query is executed.

Step 3 – API Layer Routing¶

The request is routed through the API layers (Experience → Process → System) following the standard Integration Hub layered architecture.

Step 4 – MLWH Query Execution¶

The System API executes a parameterised SQL query against MLWH using the resolved run ID list.

The query:

• Filters records using the provided run IDs
• Retrieves sample name, supplier name, study identifier, sequencing technology, paired read flag, and lane
• Retrieves iRODS storage location (root collection and relative path)
• Joins the relevant MLWH tables
• Applies LIMIT and OFFSET for pagination
• Uses parameterised inputs to prevent SQL injection

Step 5 – Response Mapping¶

Database records are mapped into a consistent JSON structure. Each row becomes a sample object within the samples array. The response also includes the pagination parameters (limit, offset) and total record count (count).

Data Sources¶