HL7 Norway
FHIR Implementation Guide for the Norwegian Municipal Sector
Shared starting point for understanding and consistent use of FHIR in municipal health and care services.
Norwegian

FHIR Implementation Guide for the Norwegian Municipal Sector
0.2.0 - ci-build NO

FHIR Implementation Guide for the Norwegian Municipal Sector - Local Development build (v0.2.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

API

This page describes API principles and documentation requirements for this IG.

What This Page Controls

The API page controls:

  • how searches are linked to prioritized use cases
  • which API requirements are normative in v0.2
  • which expectations apply to CapabilityStatement

What Matters Most In v0.2 (Guidance)

  • API use should be use case driven: clinical and operational needs are linked to concrete FHIR searches.
  • Clients retrieve patient data using standard FHIR REST/search.
  • Planned contacts should use Appointment where they are shared before completion. Completed contacts should still use Encounter.
  • "No data found" is interpreted as a valid empty result, not automatically as an error.
  • v0.2 is a pragmatic minimum without new custom operations.
  • v0.2 primarily describes read and search in a FHIR API.
  • Full support for create, update and documentation write-back is not part of the normative minimum in this version.
  • This is aligned with ongoing national work in the Norwegian Association of Local and Regional Authorities (Kommunesektorens organisasjon, KS) and the Norwegian Health Network (Norsk helsenett, NHN), where municipal interoperability services and modernized Welfare Technology Hub (Velferdsteknologisk knutepunkt, VKP) are moving towards API-based information services.

Prioritized Minimum Resource Set (Guidance)

  • Patient
  • Encounter
  • EpisodeOfCare
  • CarePlan
  • DocumentReference
  • ServiceRequest

These resources should use the municipal profiles where such profiles are defined: no-kommune-ServiceRequest, no-kommune-Encounter, no-kommune-EpisodeOfCare and no-kommune-CarePlan.

Recommended supporting resource when planned contacts are exposed:

  • Appointment

Planned contacts should use no-basis-Appointment where the national base profile is applicable. This does not make a separate no-kommune-Appointment profile part of the v0.2 minimum.

Next wave, not normative minimum in v0.2:

  • MedicationStatement
  • AllergyIntolerance
  • Condition
  • Observation

Observation is especially relevant as a next step because National Early Warning Score 2 (NEWS2) measurements, Patient's measurement data (Pasientens måledata, PMD) and modernized VKP all point towards structured sharing of measurements and assessments.

Relation To PMD/VKP (Normative Boundary)

  • This IG SHALL NOT define competing endpoints, profiles or bindings for Patient's measurement data (PMD) or VKP.
  • Measurement data shared through PMD/VKP SHOULD follow the PMD/VKP information model and API documentation.
  • Municipal APIs MAY refer to relevant Observation resources as supporting data, but SHOULD document whether measurements are retrieved from a local journal, VKP, PMD or another source.
  • When the same user interface uses both this IG and PMD/VKP, the CapabilityStatement or service documentation SHOULD describe which resources come from which service.

Relation To Trust Framework And Security (Guidance)

This IG describes FHIR resources, profiles and search patterns. It does not by itself decide whether a user or system is allowed to access a patient's information.

Implementations SHOULD document the surrounding trust and security model, including authentication, authorization, legal basis for access, organization trust, logging and follow-up/audit. In a Norwegian cross-organizational setting, this will often be related to HelseID, OAuth/OpenID Connect and the national trust framework. Such requirements belong in the API/security documentation and CapabilityStatement, not as separate municipal data profiles.

FHIR references between resources SHALL NOT be interpreted as proof that the requesting party has access rights to all referenced resources. Access control is evaluated by the service and its trust framework.

See also Use cases for full context and more examples.

Prioritized use case Resources Search example
Discharge and follow-up EpisodeOfCare, CarePlan GET [base]/EpisodeOfCare?patient=Patient/[id]&status=active and GET [base]/CarePlan?subject=Patient/[id]&status=active
Planned follow-up ServiceRequest, Appointment, Encounter GET [base]/ServiceRequest?subject=Patient/[id]&status=active, GET [base]/Appointment?patient=Patient/[id]&date=ge[YYYY-MM-DD]&status=booked and GET [base]/Encounter?patient=Patient/[id]&date=ge[YYYY-MM-DD]
Service need and decision DocumentReference, ServiceRequest GET [base]/DocumentReference?subject=Patient/[id]&type=[code] and GET [base]/ServiceRequest?subject=Patient/[id]&status=active

The search examples are intentionally standard FHIR searches. Implementations SHOULD document if they require _profile, custom search parameters or additional filters.

Normative Main Points

  • Each prioritized use case SHALL have at least one documented recommended search pattern in the IG.
  • Services SHOULD represent a valid empty search result as an empty Bundle.

Empty Search Results And Error Responses

  • A successful search with no matches SHALL return HTTP 200 with Bundle.type=searchset and no entries in entry.
  • Clients SHOULD treat such a response as a valid empty result.
  • Request errors, such as invalid parameter format, SHALL return 4xx with OperationOutcome.

Boundary For Write-Back And Documentation

  • v0.2 SHALL NOT be understood as a requirement for full support for create, update or delete of resources.
  • v0.2 SHALL NOT be understood as a complete specification for writing documentation from external systems into municipal EHRs.
  • If an implementation supports write-back or documentation submission, this SHOULD be described explicitly in separate service documentation and in CapabilityStatement where relevant.

API Versioning

  • API versioning SHALL follow SemVer principles (MAJOR.MINOR.PATCH).
  • MAJOR changes, meaning breaking changes, SHALL be published so clients can distinguish old and new API versions, for example by a separate URL path.
  • MINOR/PATCH changes SHALL be backwards compatible for existing clients.
  • API version and FHIR version SHALL be treated as separate versioning tracks.

Search, Operations And CapabilityStatement

  • The API SHALL document which searches are supported per resource.
  • The API SHALL document which central FHIR searches are not supported.
  • The API SHALL document which operations are supported, or state that no custom operations are supported.
  • Custom search parameters SHALL be described as SearchParameter and listed in CapabilityStatement.
  • Custom operations SHALL be described as OperationDefinition and listed in CapabilityStatement.
  • Any deviations from standard FHIR REST behavior SHALL be documented explicitly.
  • If an implementation supports booking, rescheduling, appointment response or other workflow operations beyond read/search, these operations SHALL be documented explicitly and listed in CapabilityStatement.

Search By National Identifier (FNR/DNR)

  • Search by national identifier SHOULD use POST [base]/<Resource>/_search to reduce the risk of sensitive information being logged in URLs.
  • If a service requires POST for such searches, this SHALL be stated in CapabilityStatement.
  • The requirement SHOULD also be documented clearly in this IG for each relevant resource (Patient, Person, RelatedPerson).

References