contracts · versioning · backward compatibility
Charles Trinh — API Design and Versioning, Las Vegas NV

Designing APIs that survive their consumers: explicit contracts, additive change, deprecation windows, and versioning that does not fork the estate.
The contract is the product
An API is a promise to strangers; every field you expose is a commitment and every field you omit is a decision.
Publish the contract as an artefact — OpenAPI or a capability statement — and generate both the documentation and the validation from it.
A contract that is written by hand and checked by nobody will be accurate for one release.
Additive change first
Add fields, never repurpose them; add endpoints, never silently change an existing one.
New optional fields are backward compatible; making an optional field required is a breaking change regardless of what the changelog says.
Track consumer usage before removing anything, because the caller you break is always the one nobody remembered.
Versioning strategy
Version at the path or in the media type, pick one, and be consistent because inconsistency costs more than either choice.
Avoid multiplying major versions: two live versions is a supportable burden, five is a fork of your own estate.
Date-based versions invite confusion about ordering; semantic versions invite arguments about meaning. Choose and document.
Deprecation that works
Announce with a date, instrument usage, contact the heaviest callers directly, and hold the removal until traffic falls or the date passes.
A deprecation nobody measured is an outage with a prior announcement.
Keep a sunset header so a caller can discover the date from the response rather than from a mailing list.
Errors as contracts
Error shape, codes and semantics are part of the API; changing them breaks callers exactly as much as changing a success payload.
Document every code, with an example, and treat the list as append-only.
A caller that cannot distinguish retryable from permanent will retry everything.
Testing the contract
Consumer-driven contract tests catch the break before the caller does, and they cost less than the incident.
Run them in the pipeline against a pinned consumer version rather than against a hypothetical client.
Where consumers cannot test, record the risk explicitly and hold the old behaviour longer.
How I do it
One trace of a real case with timestamps at every hop, before any document is written.
A findings list naming the defect, the system, the owner and the date, reviewed monthly.
No attestation I did not test, and no template sold as an assessment.
Designing the first release
Most versioning pain is created in the first release by exposing internal identifiers and internal states publicly.
Expose the stable concept and keep the internal one private, even when the mapping is one to one today.
The rule is cheap now and expensive later, because a public identifier becomes a contract the moment a consumer stores it.
Change review
Every contract change should be reviewed by someone who represents consumers, not only by the team producing it.
Keep that reviewer named and rotate slowly, because the value is accumulated knowledge of what breaks callers.
Record the decision for each change, including the ones that were additive, so the history explains the shape.
Documentation and discovery
A consumer finds the API through documentation that is generated and complete, or through asking a person, which does not scale.
Publish the capability statement, the examples and the error catalogue together, and keep them versioned with the contract.
Documentation that lags by two releases is worse than none, because it creates confident wrong integrations.
Operating the lifecycle
Track version usage per consumer, publish the retirement date, and contact the heavy users before the date rather than after.
Retire aggressively once usage reaches zero, because a version kept alive for a hypothetical caller is a tax on every future change.
Review the lifecycle quarterly with the same rigour as an incident review.
Pagination, filtering and limits
Any endpoint that returns a collection will eventually return more than a caller can handle, and the design decision is whether that is safe when it happens. Cursor pagination with a stable sort key, an explicit maximum page size and a documented default protects both the caller and the service; offset pagination on a changing dataset produces duplicates and gaps that a clinical workflow will notice. Choose the cursor before the first consumer arrives, because changing pagination later is a breaking change.
Filtering has the same character: the set of supported filters is part of the contract, and an unsupported filter that is silently ignored is a correctness bug that looks like an empty result. Reject unknown filters with a clear error and publish the supported list. The cost is a slightly stricter API and the benefit is that a caller cannot believe they have filtered a result set they have not.
Idempotency and retries
Networks retry, and a clinical write that happens twice is a different problem from one that happens zero times. An idempotency key on mutating endpoints, honoured for a stated window, turns a retry into a no-op and makes the client's life simple. Without it, every consumer invents its own deduplication, and the ones that do not are discovered during reconciliation.
Document the window and the behaviour on a key reuse with different content, because that is the case that produces corruption rather than duplication. A key reused with a different body should be rejected with a specific error, not treated as a new operation. Both behaviours are defensible; only one is safe when the client is retrying after a timeout it cannot interpret.
What consumers actually need
Consumers need to know what changed, when it changed and what they must do, and none of that arrives through a changelog nobody subscribes to. A machine-readable changelog, a sunset header on deprecated endpoints and a contact path for breakage cover the practical need. The most valuable single thing is a test account that behaves like production, because a consumer who can test against it does not need to ask questions.
Usage telemetry closes the loop: which endpoints, which versions, which consumers, and the shape of their traffic. Without it, deprecation is a guess and capacity planning is a guess. With it, the retirement date is a fact and the heaviest consumer is a name rather than a suspicion. Collect the minimum that answers those questions and keep it out of the logs where it would mix with payload data.
Security is part of the contract
Authentication and authorisation failures are contract changes from the consumer's perspective, and they deserve the same deprecation discipline as a removed field. Publishing how tokens are obtained, what scopes exist and what each endpoint requires saves every consumer an integration attempt, and it makes an authorisation change a visible event rather than a support ticket. Scope names should be stable for the same reason field names are.
Rate limits belong in the contract too: the limit, the window, the response when exceeded and how to request more. An undocumented limit is discovered as a mysterious failure under load, and the consumer's reasonable response is to retry harder. Documenting it turns a shared resource into a negotiated one, which is what it always was.
Proof
- ONC (g)(10) self-test PASS, 317 of 317 subtests, April 2026 — public suite URL
- 67 public hostnames, 51 serving, one AWS account
- 104 clearinghouse enrolments across 53 jurisdictions
- USCDI v7 proposal — Patient Digital Identity Credential — listed at isp.healthit.gov
- SAM.gov UEI MVKQW9DKKGB8 · CAGE 20KM5 · NPI 1194645564
- AWS Business Associate Addendum active since 18 August 2026
Where this work is delivered
Engagements run from Las Vegas and reach across the valley: clients in Las Vegas, NV; Las Vegas, Nevada; Henderson; Clark County, Nevada; and North Las Vegas, Nevada — plus remote delivery nationwide.
How an engagement runs
1. Trace one real case
Follow a single patient or claim end to end with a timestamp at every hop, before any document is written.
2. Written findings
A findings list naming the defect, the system, the owner and the date.
3. Monthly review
Review the list monthly and check whether the dates held.
Frequently asked
What is this service?
This page describes charles trinh — api design and versioning, las vegas nv — the scope, the failure modes it prevents and how the work is measured. It sits in the Data and Ledgers category at trinh.io.
Where is the work delivered?
Engagements run from Las Vegas, Nevada across the valley — Las Vegas, Henderson, North Las Vegas, Spring Valley, Paradise, Winchester, Sunrise Manor, Enterprise, Summerlin, Clark County — and remotely anywhere in the United States. On-site work in the Las Vegas valley, remote delivery elsewhere.
What does it cost?
Standard rate $195 per hour, committed $165 per hour at twenty hours or more per week for three months or more; $1,600 standard day, $1,350 committed day. Scoped in writing before work starts, fixed fee where the deliverable is defined.
Who is Charles Trinh?
A technology architect in Las Vegas, Nevada, working in healthcare identity, consent and interoperability. Not a physician, not a medical practice, and not affiliated with any other Charles Trinh.
How does an engagement start?
With one trace of a real case and a written findings list naming the defect, the system, the owner and the date. The first call is twenty minutes and free: 702-559-3489.
Engagement
Scoped in writing before work starts; fixed fee where the deliverable is defined. First call is 20 minutes and free. 702-559-3489 · charles@trinh.io
Talk to Charles
- Phone: 702-559-3489
- Email: charles@trinh.io
- Based in Las Vegas, Nevada · working remotely across the United States
Record
Profile
Healthcare technology architect working where federal regulation becomes production infrastructure. Built and operates a FHIR R4 clinical platform — SMART App Launch authorization server, patient and provider portals, SQLite — on a hardened single-host AWS estate of 67 public hostnames. The platform returned a self-test PASS on the ONC (g)(10) Standardized API test suite in April 2026, 317 of 317 subtests, publicly verifiable. Designed a consent architecture in which a permissioned ledger records patient grant, refusal and revocation as immutable events while all clinical data stays off-chain and encrypted per patient — no PHI on the ledger by design. Filed a proposed USCDI v7 data element with ONC on verifiable patient identity. Translates the Federal Register, HHS/CMS guidance and HITRUST requirements into architecture, controls and audit evidence.
Selected engineering scale
- Self-managed estate of 67 public hostnames, 51 serving, on one AWS account.
- FHIR R4 API with a SMART App Launch authorization server; patient and provider portals; an AI service layer; Hyperledger Fabric peer, orderer and CA; IPFS; a 337-table SQLite clinical store.
- Two permissioned distributed ledgers in production, one operating a consent registry that records grant, refusal and revocation with no PHI on chain.
- X12 005010 pipelines across eight transaction sets.
- Designed, built, deployed and operated end to end by one person.
Credentials and standards work
- Inferno (g)(10) self-test PASS, 317 of 317 subtests, April 2026 — the ONC Standardized API test suite. Standards validated: US Core 6.1.0, USCDI v3, SMART App Launch 2.0.0, Bulk Data 2.0.0. Public suite URL.
- USCDI v7 public comment submission, April 2026 — proposed Patient Digital Identity Credential under the Provenance data class, listed publicly on the ONC Interoperability Standards Platform.
- SAM.gov UEI MVKQW9DKKGB8 · CAGE 20KM5 · NPI 1194645564. AWS Business Associate Addendum active 18 August 2026.
Technical environment
AWS us-east-1 (compute, storage, messaging, SMS, email, voice) · Linux and systemd hardening · nginx · Fabric and EVM ledgers · FHIR R4 · X12 005010 · HL7 · SQLite · self-hosted mail, drive, search and monitoring · Git-based change control and CI release gates.