Expose a legacy registry as a protected API
Use this pattern when a registry has to stay where it is (a legacy database, a vendor system, a periodic export), but a partner needs an auditable read path the registrar can govern.
Starting situation
Section titled “Starting situation”A civil registration authority maintains birth and death records in a Microsoft Access database refreshed nightly from district offices. A social-insurance authority needs an authoritative vital-status answer for pension continuations. The registrar will not hand out database credentials and wants a narrow, auditable read path that leaves the source untouched.
What you set up
Section titled “What you set up”Deploy Registry Relay in front of the Access export or a read replica. Configure a consultation route that accepts a national identifier and returns only the fields the policy allows (alive/deceased flag, date of last update, issuing district).
Registry Relay owns the external HTTP contract, caller authorization, request validation, response shaping, and the provenance fields that go into audit records. The source database continues to own records, correction workflows, retention rules, and operational availability.
Use Registry Manifest to render an OpenAPI description, a JSON Schema, an SHACL shape, and an ODRL policy document for that route. Publish them as a static metadata bundle or expose them through a Relay metadata endpoint. Partners can read those artifacts before they write a single line of client code.
What a caller does
Section titled “What a caller does”The social-insurance workflow sends an authorized GET request to the Relay consultation route, passing the national identifier as a path or query parameter. The caller authenticates with the identity provider the registry operator has configured.
What the caller gets back
Section titled “What the caller gets back”Relay evaluates the authorized scope, queries the source, and returns a JSON response containing only the disclosed fields. A provenance object in the response names the issuing registry, the evaluation timestamp, and the route identifier. The full civil record, internal district notes, and correction history do not appear in the response.
Related patterns
Section titled “Related patterns”For evidence narrower than a field set (a single yes/no predicate), see Verify a business registry status without sharing the full record or Verify an eligibility or entitlement fact without sharing the full record.