Chapter 5
Phase 1 of WIA-BIO-021 fixed what a registry record looks like: a part identifier, a sequence, a metadata block, an SBOL fragment and characterisation data. Phase 2 makes those records reachable over HTTPS. A synthetic biologist rarely wants "the registry" as a whole. The questions are narrow: which promoters work in E. coli BL21(DE3), which composite parts include this ribosome binding site, what did another lab measure for this reporter, and can I submit my own plate-reader data against a part I used.
The Phase 2 surface answers three families of question: search (find parts), characterisation (read or contribute measurements) and composition (walk the structure of a composite part). The sections below follow that order. They then cover bulk loading, retry safety and notifications, which matter once a registry is fed by instruments and pipelines rather than by one person at a keyboard.
All resources live under the versioned path /registry/v1/. The seven core operations are shown below, and the host advertises them through the discovery path /.well-known/wia-synthetic-bio-registry.
GET /registry/v1/parts # search parts (paginated)
GET /registry/v1/parts/{id} # fetch part record
POST /registry/v1/parts # contribute new part
GET /registry/v1/parts/{id}/sequence # raw sequence (FASTA/GB/SBOL)
GET /registry/v1/parts/{id}/characterisation # measurement data
POST /registry/v1/characterisation # contribute measurement
GET /registry/v1/parts/{id}/composition # composite-part subgraphThe split reflects how the data is used. The part record is light enough to list in bulk. The sequence is a separate resource because a design tool wants it as FASTA, GenBank or SBOL and does not need the rest of the record. Characterisation is separate because it grows over time as new labs contribute measurements.
A part can be found by chassis, type, length, GC content, function (free text), associated keyword, design tool, contributing institution and licence. These are the criteria a bench scientist or a design-automation tool actually uses. Chassis and licence filters are the most consequential: a part characterised only in one host should not be offered blindly for another, and a part under a restrictive material-transfer licence may be unusable in a given project.
| Mechanism | Rule |
|---|---|
| Pagination | ?after=cursor&limit=N, with limit capped at 100; cursors are opaque and clients must not decode them |
| Sorting | ?sort=field&order=asc|desc, with a comma-separated list for multiple fields |
| Equality filter | ?field=value |
| Operator filter | ?field[op]=value with gte, lte, in or like |
| Navigation | Link headers following IETF RFC 8288 |
Each match in a search response carries the SBOL fragment plus the metadata block. A client can therefore render a result list, or hand the fragment to a design tool, without a second round trip per part.
Parts carry their own version history (Phase 1). The API is versioned separately, by path (/v1/, /v2/). New optional fields can appear without a major bump, so a client that ignores unknown fields keeps working. Renaming or removing a field requires a major bump and a 12-month deprecation window under IETF RFC 8594 and 9745. During that window the Deprecation and Sunset response headers tell clients the timeline. Within the 1.x line, every existing endpoint must stay reachable, and hosts may add fields but not remove them. For a registry whose part identifiers are cited in publications, this stability is as important as the sequences.
Registry data has several kinds of consumer, and the API has to serve all of them. Design software wants sequence and composition and tends to make many small, automated requests. Wet-lab teams want characterisation data under stated conditions and licence terms. Institutions that run their own repositories want to exchange whole collections. Repositories such as iGEM's parts registry, Addgene, SynBioHub and GenBank already hold overlapping information, so a new registry earns its place through consistent identifiers, comparable measurements and clear links to those neighbours, not through duplicating them. The rate tiers and bulk import path described later follow from this mix of interactive and machine traffic.
A part sequence says what a part is. It does not say how it behaves. A promoter's strength depends on the host strain, the medium, the induction profile, the temperature and the instrument. A characterisation without that context cannot be compared with anyone else's. Phase 2 therefore treats context as mandatory in what POST /registry/v1/characterisation accepts: a measurement envelope with the chassis, medium, induction profile, instrument (plate reader, flow cytometer, qPCR or RNA-seq), raw measurement data, the processing pipeline (script plus version) and the derived characteristic values.
The shape of a quantitative measurement from the data model is below.
{
"type": "fluorescence",
"value": 15000,
"unit": "RFU",
"stdDev": 1200,
"replicates": 3,
"conditions": {
"temperature": 37,
"timePoint": 6,
"timeUnit": "hours",
"opticalDensity": 0.6
},
"method": "Plate reader - Tecan Infinite M200",
"date": "2024-08-15"
}Fluorescence in relative units means little on its own. It becomes useful with the replicate count, the standard deviation, the optical density at sampling and the time point, because those let a reader judge whether two labs' numbers can be compared. Growth curves are stored as OD600 time series with a maximum growth rate, strain and medium (for example LB with chloramphenicol). Expression data for protein-coding parts separates transcript level (e.g. by qRT-PCR), protein level (e.g. Western blot quantification) and specific activity. A reader can therefore see whether a weak output comes from poor transcription or poor translation.
Submissions are checked against the chassis the part declares and reviewed asynchronously. A measurement that arrives is not immediately authoritative. A characterisation.reviewed event follows once review finishes. The reusability block (timesUsed, successRate, averageRating, reviews and citations) records community experience. It supplements measurements and does not replace them.
Most useful constructs are composites: a ribosome binding site, a promoter and a reporter assembled into one unit. GET /registry/v1/parts/{id}/composition walks the SBOL Component graph from the requested root and returns every sub-component and the relationships between them. A user can ask what a composite is made of, and, working from a basic part, can see where it has been reused.
Cycles are broken with a truncated flag. When a consumer sees it, it can re-query from a deeper node instead of receiving an unbounded graph. This keeps responses bounded even for heavily nested designs while still letting a client reconstruct the whole structure step by step.
No synthetic biology registry stands alone, so the specification defines how records move between registries. Each neighbour is handled differently.
BBa_K123456). Export converts to iGEM XML, maps the metadata fields and preserves part ID and version.plasmidId, url, availability and price. The digital part then points to something a lab can order.MN123456) and its URL, tying the registry part to the public sequence record.The sequence endpoint can return FASTA, GenBank or SBOL, which matches these exchange paths. Preserving the original identifier and version across every hop lets a team trace a part back to its source after it has passed through several repositories.
Labs and institutions often load hundreds of parts at once, for example a whole competition year or a library from a DNA synthesis vendor. POST /registry/v1/parts/bulk accepts up to 1000 parts per request, each in the canonical Phase 1 envelope. The response reports success or failure per entry, so partial success is the normal outcome: a few malformed parts should not discard hundreds of valid ones. Idempotency for a bulk request is keyed by the SHA-256 of the sorted part-identifier list, so retrying the same batch returns the cached response instead of creating duplicates.
Single contributions follow the same principle through an Idempotency-Key header (a UUID v4 or a 128-bit random token). The server caches the response for 24 hours per tenant, endpoint and key. Replaying the key returns the cached response without re-executing. Replaying it with a different body returns 409 Conflict. A contribution looks like this:
POST /registry/v1/parts HTTP/1.1
Authorization: Bearer eyJhbGc...
Content-Type: application/json
Idempotency-Key: 4f3d2c1b-9e8a-4b7c-8d6f-1a2b3c4d5e6f
{
"partId": "WIA_BBa_K2456001",
"name": "RBS-PtetR-mNeonGreen",
"type": "composite",
"sequence": "ATGGCCAAAGTC...",
"chassis": ["E. coli MG1655", "E. coli BL21(DE3)"],
"license": "OpenMTA",
"designer": "doe.j@example.org"
}The response returns the registry-assigned identifier, a canonical sequence hash and a time-stamped contribution receipt. The sequence hash makes it possible to detect that two differently named submissions are the same DNA. Note also that the example lists two chassis and states a licence, which are the two attributes users filter on most.
Three request tiers apply per hour: 1000 requests for unauthenticated clients (read-only paths only), 5000 authenticated and 10000 for the premium tier. Bulk imports also count their parts against an additional per-tenant quota. The webhook events let a downstream system react without polling.
| Event | Typical consumer action |
|---|---|
part.created, part.updated | Refresh a local design-tool index |
part.deprecated | Warn users of constructs that include the part |
characterisation.contributed | Notify the part's owner of new data |
characterisation.reviewed | Mark a measurement as accepted or rejected |
Deliveries are signed with HMAC-SHA256. A failed delivery is retried three times, at 1, 4 and 16 seconds, and then goes to a dead-letter queue. The part.deprecated event matters scientifically as well as operationally, because a retired part may be associated with a flawed sequence or a failed characterisation. For access, the surface uses OAuth 2.0 with OpenID Connect for human sessions, mutual TLS between institutions and scoped per-tenant API tokens rotated every 90 days for SDKs.
The specification describes an advisory GraphQL surface that mirrors the REST endpoints for tenants that prefer one graph. It offers part, characterisation, composition and provenance queries, mutations for the contribution flows, and subscriptions for the webhook event set. Composition is naturally graph-shaped, so a design tool that already thinks in terms of nested components may find this a better fit than repeated REST traversals. Because it is advisory, the REST endpoints remain the reference contract.
The registry ecosystem is a set of complementary roles. iGEM's registry popularised the idea of a shared catalogue of standard parts. Addgene connects digital records to distributed physical plasmids. SynBioHub offers an SBOL-native repository that labs can host themselves. GenBank anchors sequences in the public record. A WIA-BIO-021 registry sits among them as a service that keeps rich, comparable characterisation data and licence information, and that links outwards through stable identifiers, as in the cross-reference blocks shown in 5.7.
The BioBrick idea is that parts sharing the same flanking sequences can be joined in a predictable way. In the standard assembly method, each part is flanked by a prefix containing EcoRI and XbaI sites and a suffix containing SpeI and PstI sites. XbaI and SpeI produce compatible cohesive ends. One part is cut with EcoRI and SpeI, another with XbaI and PstI, and ligating them gives a composite that still carries the outer prefix and suffix, so it can serve as a part in the next round. The junction is a short "scar" that neither enzyme recognises again, which keeps assembly repeatable. The registry's role is to record the identifier, the sequence including the flanking sites, the type and the composition, so that the composition endpoint can reconstruct how a composite was built from its basic parts.
iGEM is an annual student competition built around designing and building genetic systems. Teams use parts from the registry, document new parts with measurements and contribute them back, which is why registry identifiers carry the BBa_ prefix. The competition shows why the Phase 2 workflow is shaped as it is. A burst of contributions from many small teams, mostly inexperienced with data standards, calls for bulk import, asynchronous review and mandatory measurement context. The WIA example identifier WIA_BBa_K2456001 reflects this heritage by keeping the BBa_ form.
The following client searches for composite parts in a given chassis and follows pagination through the Link header (RFC 8288). It does not decode cursors. REGISTRY and TOKEN are placeholders for your host and credential.
import requests
REGISTRY = "https://registry.example.org"
TOKEN = "..." # per-tenant API token
def find_parts(chassis, min_length=None):
params = {"type": "composite", "chassis": chassis, "limit": 100}
if min_length is not None:
params["length[gte]"] = min_length
url = f"{REGISTRY}/registry/v1/parts"
headers = {"Authorization": f"Bearer {TOKEN}"}
while url:
r = requests.get(url, params=params, headers=headers, timeout=30)
r.raise_for_status()
yield r.json() # SBOL fragment + metadata per match
nxt = r.links.get("next") # parsed from the Link header
url = nxt["url"] if nxt else None
params = None # the next link already carries them
for page in find_parts("E. coli BL21(DE3)", min_length=500):
print(page)A real finder would go on to call /parts/{id}/characterisation for the top candidates and compare the stated conditions before choosing a part.
The same interfaces serve different kinds of work. A biosensor team searches by function and chassis, then compares fluorescence measurements taken at similar optical densities. A metabolic engineering team uses composition queries to check which enzymes a pathway construct contains and reads expression data to find bottlenecks. A teaching lab downloads sequences and submits its own plate-reader data as a first contribution. A tool developer subscribes to webhook events to keep a local index current. In each case the value comes from the measurement context and the shared identifiers, not from the sequence alone.
truncated flag tell a client that calls the composition endpoint, and what should the client do next?Phase 2 turns the registry's records into three practical capabilities: filtered and paginated search, contribution and reading of context-rich characterisation, and traversal of composite-part structure. Retry-safe writes, bulk loading, webhook events and published request tiers support the machine-driven traffic that follows. The interfaces handle the central difficulty of the field, which is that a sequence alone does not predict behaviour. They do this by tying every measurement to a chassis, medium, instrument and pipeline, and by keeping identifiers stable across iGEM, Addgene, SynBioHub and GenBank.
The next chapter moves from single requests to protocols between registries. It looks at how independent registries can exchange parts and measurements across trust boundaries while keeping part identifiers, versions and licence terms intact.