Example Use Cases¶

This section provides example scenarios that demonstrate how the integration can be used.

Use Case 1: Sapio looks up an existing study before submitting a sample¶

Background¶

Before Sapio can register work against a study, it needs to confirm the study already exists as a record in Sequencescape and retrieve its canonical identifiers (id, uuid). Sapio does not hold its own copy of study data — Sequencescape remains the system of record.

Objective¶

Retrieve the Sequencescape study record matching a given name, without Sapio needing to know anything about Sequencescape's underlying API or database.

Solution¶

Sapio calls the Sapio Studies API with the study name as a query parameter:

curl 'https://api.example.com/sapio/studies/v1?name=Genomic+variation' \
  --header 'Authorization: Bearer <access_token>'

The request passes through XAPI → PAPI → SAPI → Sequencescape, matching by name, and the response is flattened before it reaches Sapio:

{
  "data": [
    {
      "id": "225",
      "name": "Genomic variation in a global set of Salmonella Paratyphi A isolates",
      "uuid": "2b0754a0-a557-11df-8092-00144f01a414",
      "created_at": "2009-01-22T11:47:13+00:00",
      "updated_at": "2024-12-04T11:08:07+00:00",
      "blocked": false,
      "state": "active",
      "ethically_approved": null,
      "enforce_data_release": true,
      "enforce_accessioning": true
    }
  ]
}

Outcome¶

Sapio now has the study's Sequencescape id and uuid, and can proceed with downstream registration steps using those identifiers, without ever needing direct access to Sequencescape.

Use Case 2: Handling an invalid search request¶

Background¶

Sapio's integration code constructs the name query parameter dynamically, and occasionally sends a request with a missing or too-short value (for example, before a user has finished typing a search term).

Objective¶

Fail fast with a clear reason, rather than passing a malformed request through to Sequencescape.

Solution¶

The name parameter is validated by the XAPI layer before any downstream call is made. For example, a request with no name at all:

curl 'https://api.example.com/sapio/studies/v1' \
  --header 'Authorization: Bearer <access_token>'

is rejected immediately with 400 Bad Request and a name parameter is required validation message — Sequencescape and the internal PAPI/SAPI layers are never called. The same applies to a name shorter than 4 characters or longer than 50 characters.

Outcome¶

Sapio's integration can treat a 400 response as a client-side input problem to fix and retry.