Beschrijving

Wanneer resources worden uitgewisseld, is de toepasselijke FHIR-versie van toepassing op de gehele interactie, niet alleen op de resources. De semantiek van de MIME-types, de RESTful URL's, de zoekparameters en de algehele interactie zijn gebonden aan een bepaalde FHIR-versie.

Overwegingen

Op dit moment wordt alleen FHIR R4 (4.0) ondersteund. Mogelijk wordt in de toekomst doorontwikkeld naar FHIR R4B (4.3). Op dat moment zijn er twee FHIR versies in beeld en dient een client te weten welke versie de FHIR resource service ondersteund.

Toepassing en restricties

Specifiek voor Koppeltaal:

In iedere URL MOET de ondersteunde FHIR versie benoemd worden.

In een URL MAG de ondersteunde API versie benoemd worden.

De FHIR resource service MOET in diens CapabilityStatement eveneens de ondersteunde versie vastleggen. 

Eisen

VER - Eisen (en aanbevelingen) voor versiebeheer

Voorbeelden

"url": "https://tst-koppeltaal.dvzaservices.nl/api/v1/domein1/fhir/r4/Task?page=1&queryId=15c25015-cae9-4ff2-9d02-38e34ba9d971"

Links naar gerelateerde onderwerpen

FHIR versioning: https://hl7.org/fhir/versioning.html

Capability Statement: CapabilityStatement (eHealth Mogelijkheden) en https://www.hl7.org/fhir/r4/capabilitystatement.html 

OUDE TEKST

Waarom versies

Het is zeer onwaarschijnlijk dat een Koppeltaal interface ongewijzigd blijft. Als de Koppeltaal eisen in der loop ter tijd  veranderen, kunnen er nieuwe verzamelingen van FHIR resources, profielen en interacties worden toegevoegd, kunnen de relaties tussen de resources veranderen en kan de structuur van de gegevens in de resources worden gewijzigd.

...

Versiebeheer moet ervoor zorgen dat een Koppeltaal interface of resource aan kan geven welke functies en FHIR resources beschikbaar worden gemaakt en een cliënt toepassing interacties kan uitvoeren die doorgestuurd kan worden naar een specifieke versie van een functie of FHIR resource.

Versiebeleid zorgt ervoor dat elke wijziging of aanpassing van een Configuratie Item (CI) een gedefinieerde versie heeft voor belanghebbenden.   

De aanpassingen die aan een Koppeltaal interface of FHIR profiel (CI) wordt gedaan, kunnen in 2 categorieën worden onderverdeeld:

• een Minor of kleine wijziging of
• een Major of grote wijziging

...

Het is afhankelijk van de implementatie wanneer een wijziging breaking of niet breaking is. Wanneer bijvoorbeeld validatie wordt toegepast op inkomende berichten en de aanroepende partij hanteert een ander versienummer dan de ontvangende partij waarbij in het bericht een element is toegevoegd, zal bij de ontvangende partij het bericht niet verwerkt worden door deze validatie. Om te voorkomen dat alle wijzigingen breaking zijn, is de keuze gemaakt om elementen in de resources optioneel te maken zodat verschillende Minor en Build versies kunnen communiceren met elkaar of te wel backwards compatible blijven. Bij integratie is het verstandig dat partijen ervan uit gaan dat wijzigingen breaking zijn en dat hiermee rekening moet worden gehouden in de implementatie. 

BELANGRIJK:

Er is nog geen (officieel) besluit genomen HOE we met verschillende versies van (FHIR) REST APIs en (FHIR) resources (profielen) om zullen gaan. Op deze pagina worden de verschillende benaderingen bekeken en beschreven wat de voor- en nadelen zijn.

Geen versiebeheer

Dit is de eenvoudigste manier en mogelijk acceptabel voor een aantal (interne) Koppeltaal interfaces. Belangrijke wijzigingen kunnen worden weergegeven als nieuwe resources of nieuwe koppelingen. Als u optionele elementen toevoegt aan bestaande FHIR resources, is er mogelijk geen wijziging die problemen geeft, omdat cliënt toepassingen die deze elementen niet verwachten te zien, dit zullen negeren.

Een aanvraag voor de URI moet bijvoorbeeld de details retourneren van Patient 61 met de velden "name" en "birthDate"

 GET https://koppeltaal.nl/fhir/Patient/61

{
    "resourceType": "Patient",   
    "id": "61",
    "identifier":  [
        {
            "use": "official",
            "system": "irma",
            "value": "berendbotje01@vzvz.nl"
        }
    ],
    "active": true,
    "name":  [
        {
            "text": "Berend Botje",
            "family": "Botje",
            "given":  [
                "Berend"
            ]
        }
    ],
    "birthDate": "1970-12-20" 
}
  

Als het optionele element "gender" wordt toegevoegd aan de resource instantie zouden bestaande toepassingen goed moeten blijven werken als ze in staat zijn om niet-herkende elementen te negeren, terwijl nieuwe toepassingen kunnen worden ontworpen voor het afhandelen van dit nieuwe element. Als echter ingrijpender (verplichte) wijzigingen in het schema van de resources optreden (zoals verwijderen of wijzigen van elementen) of de relaties tussen resources worden gewijzigd, kan dit bestaande toepassingen zodanig beïnvloeden dat deze niet meer correct werken. In deze (Major) situaties moet u één van de volgende benaderingen overwegen.

...

URI-versiebeheer

Telkens wanneer een Koppeltaal interface wijzigt of het schema van de resources wordt aanpast, voegt men een uniek (major) versienummer toe aan de URI voor elke (FHIR) resource. De bestaande URI's moeten blijven functioneren als voorheen en resources retourneren die voldoen aan hun oorspronkelijke schema.

...

Dit mechanisme voor versiebeheer is zeer eenvoudig, maar is afhankelijk van de FHIR Resource Provider die de aanvraag naar het juiste eindpunt moet doorsturen. Dit mechanisme kan onhandig worden als de Koppeltaal interface via verschillende iteraties groeit en de FHIR Resource Provider een aantal verschillende versies moet ondersteunen. Vanuit het oogpunt van een purist halen de toepassingen in alle gevallen dezelfde gegevens op (Patient 61), dus de URI mag niet echt verschillen, afhankelijk van de versie. FHIR referenties wordt door dit mechanisme ook ingewikkelder, omdat alle referenties het versienummer moeten opnemen in hun URI's.

Header-versiebeheer

In plaats van het versienummer in het URI toe te voegen, kan men een aangepaste (HTTP) header implementeren die de versie van de resource aangeeft. Deze aanpak vereist dat de toepassing de juiste header toevoegt aan alle aanvragen, hoewel de code voor het verwerken van de aanvraag een standaardwaarde (versie 1) kan gebruiken als de versie-header wordt weggelaten. In het volgende voorbeelden wordt een aangepaste header met de naam Custom-Header gebruikt. De waarde van deze header geeft de versie van de Koppeltaal interface aan.

GET https://koppeltaal.nl/fhir/Patient/61 HTTP/1.1

Custom-Header: Koppeltaal-version=2

Net als bij de vorige benadering moet men voor het implementeren van FHIR referenties de juiste aangepaste header in koppelingen toevoegen.

Response header

...

Voorbeeld van een response header: API-Version: 1.0.2

Mediatype-versiebeheer

Wanneer een cliënt toepassing een HTTP GET-aanvraag naar de FHIR Resource Provider verzendt, moet deze de indeling van de inhoud bepalen die het kan verwerken met behulp van een Accept-header. Vaak is het doel van de Accept-header ervoor te zorgen dat de cliënt toepassing op kan geven of de inhoud van het antwoord XML, JSON of een andere algemene indeling moet zijn, die door de cliënt kan worden verwerkt. Het is echter mogelijk aangepaste media typen te definiëren met informatie voor het inschakelen van de cliënt toepassing, om aan te geven welke versie van een FHIR resource wordt verwacht.

In het volgende voorbeeld is een aanvraag met een Accept-header met de waarde application/koppeltaal.adventure-works.v2+json. Het koppeltaal.adventure-works.v2-element geeft bij de FHIR Resource Provider aan dat versie 2 van de resource aan de cliënt toepassing moet worden geretourneerd, terwijl het json-element aangeeft dat de indeling van de inhoud JSON moet zijn.

...

Als de Accept-header geen bekende media typen opgeeft, kan de FHIR Resource Provider een antwoordbericht HTTP 406 (Niet aanvaardbaar) genereren, of een bericht retourneren met een standaard-mediatype. Deze aanpak is misschien de zuiverste van de verschillende methoden voor versiebeheer en is van nature geschikt voor FHIR referenties, dat het MIME-type van gerelateerde gegevens in links naar resources kan opnemen.

Het Open API Initiatief voor versiebeheer van interfaces

Het Open API Initiatief is gemaakt door een brancheconsortium om (FHIR) REST-API-beschrijvingen bij leveranciers te standaardiseren. Als onderdeel van dit initiatief kreeg de Swagger 2.0-specificatie de nieuwe naam OpenAPI Specification (OAS) en werd deze onder het Open API Initiatief gebracht.

Wellicht kan men het OpenAPI overnemen voor het beheer van de verschillende Koppeltaal interfaces. Enkele punten om in overweging te nemen:

• De OpenAPI Specification wordt geleverd met een set van richtlijnen over hoe een REST-API moet worden ontworpen. Dit heeft voordelen voor interoperabiliteit, maar vereist meer zorg bij het ontwerpen van de Koppeltaal interfaces om te voldoen aan de specificatie.

• OpenAPI draagt bij aan een contract-eerst-benadering, in plaats van een implementatie-eerst-benadering (zie onze referentie implementatie). Contract-eerst betekent dat de Koppeltaal interface-contract (de interface) eerst ontwerpt en vervolgens de code schrijft die het contract implementeert.

• Hulpprogramma's zoals Swagger kunnen client bibliotheken of documentatie van de API-contracten genereren. Zie bijvoorbeeld helppagina'ASP.NET web-API met behulp van Swagger.

FHIR Profielen voor versiebeheer van resources

FHIR resources zijn in de basis generiek en worden met behulp van profielen uitgebreid en specifieker gemaakt voor een specifieke toepassing. In een profiel wordt bijvoorbeeld beschreven:

• Versie identifier die gebruikt wordt om de versie van de structuur te identificeren wanneer ernaar wordt verwezen in een specificatie, model, ontwerp of exemplaar. 
• Welke resource elementen worden gebruikt en welke niet en welke additionele elementen worden toegevoegd die geen onderdeel zijn van de basisspecificatie van een FHIR basis set.
• Welke API interacties worden er gebruikt voor een bepaalde resource
• Welke terminologieën worden gebruikt in bepaalde elementen
• Hoe de resource elementen mappen naar lokale eisen en/of implementaties

Door de manier waarop profielen wordt toegepast binnen FHIR kunnen er voor een bepaalde basis resource versie (DSTU 2, STU 3, R4, etc.) een groot aantal verschillende profielen bestaan, bijvoorbeeld afhankelijk van zorgdomein, land, instelling of leverancier. Om interoperabiliteit te borgen is het van belang dat binnen een bepaalde 'use case' dezelfde profielen gebruikt worden. 

Elke  FHIR basis set, bestaat uit:

• set datatypes (primitieve, algemene, meta en speciale toepassingen) 
• set resources (+/- 13 resources)
• standaard REST operaties 
• standaard zoek (search) parameters
• standaard terminologie 

Elke FHIR resource (zie het element meta.profile in een resource instantie) refereert naar een Canonical URL. Dit is een unieke identifier voor een conformance resource (uri) waaraan de resource beweert te voldoen.

Voorbeeld: een Patient die aan het KT2_Patient profiel voldoet 

{
  "resourceType": "Patient",
  "meta": {
     "profile": [ "http://example.org/fhir/StructureDefinition/KT2Patient" ]
  },
  ...
}

Deze Patient (JSON) structuur instantie beweert te voldoen aan een profile wat is vastgelegd in http://example.org/fhir/StructureDefinition/KT2Patient

De Profile legt beperkingen op FHIR basis datatypes, FHIR basis resources en eventueel op een ander FHIR profile. Verder kunnen er additionele elementen worden toegevoegd die geen onderdeel zijn van de FHIR basis set. Een profile is gelaagd (er zit een hiërarchische structuur in ).

Bijvoorbeeld:

• FHIR STU3-CORE→ FHIR NL-CORE (2017) → FHIR NL Medicatie → MedMij
• FHIR STU3-CORE→ FHIR NL-CORE (2017) → FHIR NL Medicatie → ZIB (Zorg Informatie Bouwsteen)
• FHIR R4-CORE → FHIR NL-CORE (2020) → FHIR Koppeltaal 2.0

Een register met FHIR profielen is te vinden op www.simplifier.net (deze site is opgezet in samenwerking met HL7 Nederland). Een draft versie van een Koppeltaal 2.0 profile, gebaseerd op FHIR R4 , met een National NL scope, is te vinden op Simplifier.NET. 

...

FHIR versies

Op dit moment wordt alleen FHIR R4 (4.0) ondersteund. Mogelijk wordt in de toekomst doorontwikkeld naar FHIR R4B (4.3). Op dat moment zijn er twee FHIR versies in beeld en dient een client te weten welke versie de FHIR resource service ondersteund. Om dit te ondersteunen wordt er voor gekozen de om de FHIR versie van de FHIR service duidelijk te communiceren in zowel de URL als in de MIME-type. Door de versie in de URL vast te leggen wordt ook afgedwongen dat verschillende versies op verschillende URLs beschikbaar zijn, door de versie als MIME-type te gebruiken in de Accept en Content-Type header kunnen fouten voorkomen worden.

API versies

De verschillende APIs, waaronder de FHIR API, kennen ook versies. Om deze kenbaar te maken, en om test en acceptatie processen te ondersteunen, mogen deze APIs een versie in hun URL gebruiken om zo kenbaar te maken met welke versie van de API er op dat moment gebruikt wordt. Indien er gebruik gemaak wordt van versionering in de API, moet er gebruik gemaakt van een vast versioneringssysteem waarmee onderscheid wordt gemaakt tussen brekende en niet-brekende verschillen tussen de versies.

Toepassing en restricties

FHIR versies in de FHIR service

De FHIR service MOET de FHIR versie bekend maken, Dit doen we door zowel de FHIR versie vast te leggen op de volgende plekken:

1. De FHIR versie in de URL van de FHIR service als pad toe te voegen in de URL.

2. De FHIR versie onderdeel te maken van de MIME-type als parameter in zowel de Accept header als dee Content-Type header. 

   Code Block
   Accept: application/fhir+json; fhirVersion=4.0

   
   

3. Capacity Statement van de FHIR resource service.

FHIR versies vanuit de API client

De FHIR client mag gebruik maken van de fhirVersion parameter in de Content-Type  header, maar is dit niet verplicht.

API versionering. 

De APIs in het domein, dus ook de FHIR API, mogen in hun URL de versie van hun API verwerken. Indien dit gedaan wordt, moet dit volgens het volgende nummersysteem gedaan worden:

<major>.<minor>.<build>

• Major versie nummer, een major versie omvat een breaking change aan een voorziening of toepassing waarbij de afnemer of aanbieder de software functioneel en technisch moet aanpassen om de nieuwe versie te ondersteunen.
• Minor versie nummer, een minor versie betreft aanpassingen die de bestaande functionaliteit niet aanraakt/beïnvloedt
• Build versie nummer, dit veld is verplicht en mag gebruikt worden om revisienummers uit versiebeheer of buildomgevingen te correleren. Indien niet van toepassing moet de waarde 0 gebruikt worden.

Eisen

VER - Eisen (en aanbevelingen) voor versiebeheer

Links naar gerelateerde onderwerpen

FHIR versioning: https://hl7.org/fhir/versioning.html

Capability Statement: CapabilityStatement (eHealth Mogelijkheden) en https://www.hl7.org/fhir/r4/capabilitystatement.html 

{}