Concepts
Reading one code, and walking the tree it sits in. Hierarchy is served from a closure table — do not assemble it yourself. Taught in Walking a concept tree.
The membership of a code system
The call an HMIS dropdown is built on. Version-aware: ?version=serving pins the latest approved release.
Keep from the response: code, display
query Parameters
systemThe code system short code or id.
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.
page_sizeResults per page. A sync that reads only page one ships a fraction of a vocabulary and looks like it worked.
pagePage number. Follow next in the response rather than computing this.
The membership of a code system › Responses
Returns code, display.
countnextpage_sizecurrent_pagetotal_pagesOne concept
With the identity a detail page needs: uri, owning system, and the version it was introduced in.
Keep from the response: uri
path Parameters
idThe concept. Numeric id — concept codes are unique only within a system, so this route has no code form. Resolve the id from GET /concepts/?system=<short code> and keep it alongside the code.
One concept › Responses
Returns uri.
The top of the tree
Start here when rendering a large vocabulary lazily, then walk children as the user opens nodes.
Keep from the response: root codes
query Parameters
systemThe code system to take the roots of.
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.
The top of the tree › Responses
Returns root codes.
One level down
The direct children of this concept.
path Parameters
idThe concept. Numeric id — concept codes are unique only within a system, so this route has no code form. Resolve the id from GET /concepts/?system=<short code> and keep it alongside the code.
query Parameters
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.
One level down › Responses
Success.
One level up
A concept may have more than one parent. Rendering a single breadcrumb will silently pick one.
path Parameters
idThe concept. Numeric id — concept codes are unique only within a system, so this route has no code form. Resolve the id from GET /concepts/?system=<short code> and keep it alongside the code.
query Parameters
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.
One level up › Responses
Success.
Everything beneath, transitively
Served from a closure table rather than computed by you. Fetching children repeatedly is slower and drifts the moment the vocabulary is re-parented.
path Parameters
idThe concept. Numeric id — concept codes are unique only within a system, so this route has no code form. Resolve the id from GET /concepts/?system=<short code> and keep it alongside the code.
query Parameters
page_sizeResults per page. A sync that reads only page one ships a fraction of a vocabulary and looks like it worked.
pagePage number. Follow next in the response rather than computing this.
Everything beneath, transitively › Responses
Success.
Everything above, transitively
The full set of ancestors, for a breadcrumb or a rule that inherits down the tree.
path Parameters
idThe concept. Numeric id — concept codes are unique only within a system, so this route has no code form. Resolve the id from GET /concepts/?system=<short code> and keep it alongside the code.
Everything above, transitively › Responses
Success.
Which value sets include this concept
Reverse membership. The answer to “where would a user ever be offered this code?”
path Parameters
idThe concept. Numeric id — concept codes are unique only within a system, so this route has no code form. Resolve the id from GET /concepts/?system=<short code> and keep it alongside the code.
Which value sets include this concept › Responses
Success.