FHIR operations
Code in, answer out. All are GET, all return a FHIR Parameters resource, and all are version-aware. Taught in Validating a code.
Resolve what a code means
Display, definition, designations and properties for one code.
Keep from the response: display
path Parameters
systemThe code system, addressed by its short code (recommended) or its numeric id.
Resolution is pk-first: a value that looks numeric is tried as an id, and falls through to the code column when no row matches, so an all-digits short code is still reachable. Codes are matched case-insensitively after an exact miss. The one ambiguity — a short code identical to some other row's id — resolves to the id.
Example: IDENTIFIER-TYPES.
query Parameters
codeThe code to resolve.
versionWhich version of the artefact this read serves.
serving— the version the artefact currently resolves to: the author's or regulator'sMANUALpin if one is set, otherwise the newest released version effective today. This is what an integration should send.- a released version's
version_id(v1.0.0) or its numeric id — exactly that frozen release. Only released versions are honoured; an unknown or unreleased reference falls back to the working copy with a warning rather than failing. draft— the pending draft, for reviewers. Requires the reviewer permission.
Omitted, what you get depends on the artefact: the working copy including drafts while it is unpinned, or the pinned version if an owner has set one. That is what an authoring client wants and the opposite of what a consumer wants — the problem is not that it is always live, but that you cannot tell which you got.
One exception to serving meaning frozen, and it is silent: a code system release predating the content-versioning backfill carries no ordinal, so the read serves the live working copy at 200 with no signal in the body or headers. Detect it on the artefact instead — a released version whose ladder row has sequence: null has no frozen content to serve.
A pinned read is cacheable indefinitely (Cache-Control: immutable); an unversioned one is no-cache, because its content changes on release with no write to the rows it would be cached on.
Resolve what a code means › Responses
Returns display.
resourceTypeDoes this code exist, and is it active?
Answers 200 whether or not the code is valid. The verdict is the result parameter in the body. An integration that branches on the status code treats every invalid code as accepted.
Keep from the response: result
path Parameters
systemThe code system, addressed by its short code (recommended) or its numeric id.
Resolution is pk-first: a value that looks numeric is tried as an id, and falls through to the code column when no row matches, so an all-digits short code is still reachable. Codes are matched case-insensitively after an exact miss. The one ambiguity — a short code identical to some other row's id — resolves to the id.
Example: IDENTIFIER-TYPES.
query Parameters
codeThe code to check.
versionWhich version of the artefact this read serves.
serving— the version the artefact currently resolves to: the author's or regulator'sMANUALpin if one is set, otherwise the newest released version effective today. This is what an integration should send.- a released version's
version_id(v1.0.0) or its numeric id — exactly that frozen release. Only released versions are honoured; an unknown or unreleased reference falls back to the working copy with a warning rather than failing. draft— the pending draft, for reviewers. Requires the reviewer permission.
Omitted, what you get depends on the artefact: the working copy including drafts while it is unpinned, or the pinned version if an owner has set one. That is what an authoring client wants and the opposite of what a consumer wants — the problem is not that it is always live, but that you cannot tell which you got.
One exception to serving meaning frozen, and it is silent: a code system release predating the content-versioning backfill carries no ordinal, so the read serves the live working copy at 200 with no signal in the body or headers. Detect it on the artefact instead — a released version whose ladder row has sequence: null has no frozen content to serve.
A pinned read is cacheable indefinitely (Cache-Control: immutable); an unversioned one is no-cache, because its content changes on release with no write to the rows it would be cached on.
Does this code exist, and is it active? › Responses
Returns result.
resourceTypeIs this code a member of this value set?
The binding check for a form field. Same 200-regardless rule as above: read result.
Keep from the response: result
path Parameters
value_setThe value set, addressed by its short code (recommended) or its numeric id.
Resolution is pk-first: a value that looks numeric is tried as an id, and falls through to the code column when no row matches, so an all-digits short code is still reachable. Codes are matched case-insensitively after an exact miss. The one ambiguity — a short code identical to some other row's id — resolves to the id.
Example: SHA-OUTPATIENT-DIAGNOSES.
query Parameters
codeThe code to check for membership.
versionWhich version of the artefact this read serves.
serving— the version the artefact currently resolves to: the author's or regulator'sMANUALpin if one is set, otherwise the newest released version effective today. This is what an integration should send.- a released version's
version_id(v1.0.0) or its numeric id — exactly that frozen release. Only released versions are honoured; an unknown or unreleased reference falls back to the working copy with a warning rather than failing. draft— the pending draft, for reviewers. Requires the reviewer permission.
Omitted, what you get depends on the artefact: the working copy including drafts while it is unpinned, or the pinned version if an owner has set one. That is what an authoring client wants and the opposite of what a consumer wants — the problem is not that it is always live, but that you cannot tell which you got.
One exception to serving meaning frozen, and it is silent: a code system release predating the content-versioning backfill carries no ordinal, so the read serves the live working copy at 200 with no signal in the body or headers. Detect it on the artefact instead — a released version whose ladder row has sequence: null has no frozen content to serve.
A pinned read is cacheable indefinitely (Cache-Control: immutable); an unversioned one is no-cache, because its content changes on release with no write to the rows it would be cached on.
Is this code a member of this value set? › Responses
Returns result.
resourceTypeHow two codes relate
equivalent, subsumes, subsumed-by or not-subsumed. The cheap way to ask whether a billed code falls under an approved one.
Keep from the response: outcome
path Parameters
systemThe code system, addressed by its short code (recommended) or its numeric id.
Resolution is pk-first: a value that looks numeric is tried as an id, and falls through to the code column when no row matches, so an all-digits short code is still reachable. Codes are matched case-insensitively after an exact miss. The one ambiguity — a short code identical to some other row's id — resolves to the id.
Example: IDENTIFIER-TYPES.
query Parameters
codeAThe first code.
codeBThe second code.
How two codes relate › Responses
Returns outcome.
Rank concepts by free-text match
Autocompletion against one known vocabulary.
Keep from the response: matches
path Parameters
systemThe code system, addressed by its short code (recommended) or its numeric id.
Resolution is pk-first: a value that looks numeric is tried as an id, and falls through to the code column when no row matches, so an all-digits short code is still reachable. Codes are matched case-insensitively after an exact miss. The one ambiguity — a short code identical to some other row's id — resolves to the id.
Example: IDENTIFIER-TYPES.
query Parameters
propertyProperty values to match on.
Rank concepts by free-text match › Responses
Returns matches.