Skip to main content

capabilities

Tracks a FHIR server's declared and observed resource-type support.

Classes​

FHIRServerCapabilities​

class FHIRServerCapabilities():

What resource types a single FHIR server supports.

Combines a proactive and a reactive signal, both scoped to one client (⇒ one server ⇒ one run):

  • supported: the allowlist advertised by the server's CapabilityStatement (GET [base]/metadata, rest.resource[].type). None until loaded, and stays None if the server serves no usable statement — signalling callers to fall back to the reactive signal rather than assume nothing works.
  • unsupported: resource types a live request has revealed the server does not implement (a 404 whose OperationOutcome names an unknown/unsupported type), accumulated so repeat requests can be skipped.

Static methods​

is_unsupported_type_outcome​

def is_unsupported_type_outcome(resource: Mapping[str, Any]) ‑> bool:

Whether an OperationOutcome reports an unsupported resource type.

The issue code is authoritative and checked first: only not-supported means the type is unimplemented. For any other code (including the generic processing, which does not distinguish a missing type from any other failure) we fall back to matching the human-readable diagnostics.

Outcomes scoped to something narrower than the type are excluded, as treating them as type-level would wrongly blacklist the type for the rest of the run. An issue is scoped narrower when it either carries an expression/location (which pinpoint a specific element or search parameter) or names a search parameter, interaction, or profile in its diagnostics.

Arguments

  • resource: A parsed OperationOutcome resource (or any mapping).

Returns True if the outcome indicates the server does not support the requested resource type.

Methods​

ensure_loaded​

def ensure_loaded(self, fetch_statement: Callable[[], Any]) ‑> None:

Populate supported from the CapabilityStatement, at most once.

Best-effort: fetch_statement performs the /metadata request and any failure (server error, missing/malformed/empty statement, network) is swallowed, leaving supported as None so callers fall back to the reactive signal. This tolerates non-conformant servers.

A failure is treated as retryable rather than as a verdict on the server, up to _MAX_LOAD_ATTEMPTS times across the client's lifetime. The allowlist is a pure optimisation, so a client whose first request happens to land on a network blip, a 503 or an expired token would otherwise have supported pinned to None for its whole lifetime, silently losing the allowlist for every later request. The cap stops a server that never answers from being re-asked before every call.

Arguments

  • fetch_statement: Zero-arg callable returning the parsed CapabilityStatement (a mapping), typically the client's /metadata request.

record_param_unsupported​

def record_param_unsupported(self, resource_type: str, param: str) ‑> None:

Record that param triggers a failure for resource_type searches.

Arguments

  • resource_type: The FHIR resource type that was being searched.
  • param: The search parameter that triggered the failure.

record_unsupported​

def record_unsupported(self, resource_type: str) ‑> None:

Record that the server does not support resource_type.

Arguments

  • resource_type: The FHIR resource type revealed to be unsupported.

should_skip​

def should_skip(self, resource_type: str) ‑> bool:

Whether a search for resource_type can be skipped without a request.

True when either the server's advertised allowlist is known and omits the type (proactive), or a prior request already revealed it unsupported (reactive). When the allowlist is unknown (supported is None) only the reactive signal applies.

Arguments

  • resource_type: The FHIR resource type about to be searched.

should_skip_param​

def should_skip_param(self, resource_type: str, param: str) ‑> bool:

Whether param is already known to break searches for resource_type.

Reactive only (no CapabilityStatement equivalent exists for search parameters): true once a prior search for resource_type including param has failed with an API/operation error and a retry without it succeeded. Lets a caller skip straight to the working request instead of re-paying that failure's retry cost on every subsequent search.

Arguments

  • resource_type: The FHIR resource type being searched.
  • param: The search parameter to check.