7a. The REST façade (openEHR ITS-REST)

A gateway MUST implement OPTIONS {base}/ returning a description of the federation surface: the ITS-REST areas it supports (per §7a.1 above), which are federated vs. single-node-routed, which are unsupported, the dedup mode (§10), and the gateway’s timeout policy (§11.5). (N30.)

The response MUST include the member endpoints behind the gateway - the same identifiers usable in a directive (§8) - each with at least id, organisation, and status, and SHOULD include the owning node_id (§ The four identifiers). It SHOULD include product and version as separate fields, matching §9.5, and a representative latency where the gateway tracks one.

An endpoint’s status here is membership and health information, meaning whether this member is in service. It is not the per-query status vocabulary of §11.1. The two answer different questions: this one describes the federation’s standing configuration, meta.federation.endpoints[] describes what happened to one query. A value such as not-localized means nothing here, and active here does not predict active there.

This specification does not define a closed vocabulary for the membership status. It is a free-form string whose values a deployment chooses, and a client MUST NOT assume a fixed set. active is the conventional value for a member in service, and the schema treats the field as an unconstrained string so that no implementer reads the §11.1 enum into it by default. Fixing a vocabulary here is deferred (§18), because it is a membership-lifecycle question and this release does not specify that lifecycle (§12b).

Latency reported here is an aggregate over recent requests, not the per-query measurement of §9.5; a gateway reporting one SHOULD name the statistic in the field (e.g. latency_ms_p50) so the two are not confused.

The response MUST additionally declare every behaviour this specification requires be declared under N30: whether the opt-in best-effort completeness mode is offered, and how it is selected (N37; all-or-nothing is the default and needs no declaration beyond completeness.default), the OFFSET > 0 strategy (N39), which decomposable aggregates are supported if any (§11.6.3), whether fan-out template upload is offered (N43), whether the stored-query registry and the fan-out of stored-query definitions are offered (N44, §12.7), the behaviour when localization is unavailable (§14.1), and the JWKS location (§13.1).

The accepted patient-resolution input predicates are not declared here, on purpose. Both carriers, EHR_STATUS.subject.external_ref and an ENTRY-level subject PARTY_IDENTIFIED/DV_IDENTIFIER predicate, are mandatory at every conformant gateway (§5.4.3, N33). There is nothing for a deployment to vary and nothing for a client to discover, and a key declaring them would invite the variation that the requirement removes.

The accepted targeting mechanisms are omitted for the same reason. Both the in-AQL FROM ENDPOINT directive and the openEHR-federation-endpoint header are mandatory at every conformant gateway (§8.4, N35), so the only conformant declaration is "both" and a client learns nothing by reading it. The aql object therefore carries no endpoint_directive or endpoint_header key. fan_out remains, because it describes what the gateway does with an untargeted query and says nothing about which mechanisms it accepts.

The endpoint list is federation membership information and contains no patient data. It MUST NOT be gated on a patient identifier, and it MUST be subject to the gateway’s normal authentication (§13). A deployment MAY restrict the detail returned to unauthenticated callers.

OPTIONS on a sub-path (e.g. OPTIONS {base}/v1/ehr/{ehr_id}) SHOULD return the HTTP methods allowed for that resource, per ordinary HTTP semantics.

Note that its_rest.definition describes the area as a whole while definition.stored_query_registry describes one artefact within it, and the two can legitimately differ. The example below declares templates single-node-routed and stored queries held at the gateway registry, which is the expected shape for a gateway that adopted §12.7 without changing template handling. The its_rest values are free-form descriptions of behaviour and a client MUST NOT parse them as a closed vocabulary. A client tests the definition object’s booleans programmatically.

federation.spec_version carries the version of this specification the gateway implements, in major.minor form. Patch releases are editorial and do not change the wire contract, so a gateway implementing 0.9.0 reports "0.9" and would still report "0.9" at 0.9.1. A client MUST NOT match on a patch component. A minor release may change the wire contract and so does move this value: 0.4.0 did, by correcting rows to the ITS-REST array form (Changes). 0.9.0 changes no wire structure, but it is a minor release and so moves the value too, from "0.4" to "0.9". The field identifies which release a gateway was built against, and a client pinning "0.4" should be told the document has moved on (Changes).

On every request the gateway routed or dispatched to a single node - including POST, PUT and DELETE - the gateway MUST return the acting endpoint’s identifier in the openEHR-federation-endpoint response header, and SHOULD return the node’s system_id in openEHR-federation-system-id. (N31, §9.6.)

The gateway MUST pass the node’s Location and ETag through unmodified, because openEHR uids are never rewritten (N22). The ETag of a commit is an OBJECT_VERSION_ID and so already carries the creating_system_id. The headers above are a convenience and an audit aid; they do not replace it.

These headers SHOULD also be set on federated AQL responses, listing the endpoints that contributed, but meta.federation.endpoints[] stays the normative carrier there (§11.1).