...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
| Expand | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||
|
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
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.
Hoewel het bijwerken van de Koppeltaal interfaces voor het afhandelen van nieuwe of verschillende behoeften een relatief eenvoudig proces lijkt, moet men echter rekening houden met de effecten die dergelijke wijzigingen kunnen hebben op de aanbiedende en afnemende partijen die de verschillende Koppeltaal interfaces gebruiken. Het probleem is dat, hoewel de leverancier die een Koppeltaal toepassing levert en controle heeft over die interface, geen volledige controle heeft over de voorzieningen en toepassingen, die mogelijk worden geleverd door andere organisaties. Belangrijk is het zorgen dat bestaande toepassingen ongewijzigd blijven werken, terwijl nieuwe toepassingen kunnen profiteren van nieuwe functies en FHIR resources.
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 een gedefinieerde versie heeft voor belanghebbenden.
De aanpassingen die aan een Koppeltaal interface 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.
De volgende paragrafen beschrijven enkele verschillende benaderingen, die allemaal hun eigen voor- en nadelen hebben.
Geen versiebeheer
Dit is de eenvoudigste manier en mogelijk acceptabel voor een aantal interne interfaces. Belangrijke wijzigingen kunnen worden weergegeven als nieuwe resources of nieuwe koppelingen. Als u inhoud toevoegt aan bestaande FHIR resources, is er mogelijk geen wijziging die problemen geeft, omdat toepassingen die deze inhoud niet verwachten te zien, dit zullen negeren.
...
Bestaande toepassingen blijven mogelijk goed werken als ze in staat zijn om niet-herkende velden te negeren, terwijl nieuwe toepassingen kunnen worden ontworpen voor het afhandelen van dit nieuwe veld. Als echter steeds ingrijpender wijzigingen in het schema van de resources optreden (zoals verwijderen of wijzigen van veldnamen) of de relaties tussen resources wijzigen, kan dit inhouden dat dit grote veranderingen zijn die verhinderen dat bestaande toepassingen correct werken. In deze situaties moet u een van de volgende benaderingen overwegen.
URI-versiebeheer
Telkens wanneer de Koppeltaal interface wijzigt of het schema van resources aanpast, voegt men een uniek versienummer toe aan de URI voor elke 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 server die de aanvraag naar het juiste eindpunt doorstuurt. Het kan echter onhandig worden als de Koppeltaal interface via verschillende iteraties groeit en de server een aantal verschillende versies moet ondersteunen. Vanuit het oogpunt van een purist halen de toepassingen in alle gevallen dezelfde gegevens op (Patient 3), dus de URI mag niet echt verschillen, afhankelijk van de versie. FHIR Referenties wordt door dit schema ook ingewikkelder, omdat alle koppelingen 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 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 de 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/Patient/3
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.
Mediatype-versiebeheer
Wanneer een client toepassing een HTTP GET-aanvraag naar een webserver verzendt, moet deze de indeling van de inhoud bepalen die ze kan verwerken met behulp van een Accept-header. Vaak is het doel van de Accept-header ervoor te zorgen dat de client toepassing op kan geven of de inhoud van het antwoord XML, JSON of een andere algemene indeling moet zijn, die door de client kan worden geparseerd. Het is echter mogelijk aangepaste mediatypen te definiëren met informatie voor het inschakelen van de client toepassing, om aan te geven welke versie van een FHIR resource wordt verwacht.
In het volgende voorbeeld ziet u een aanvraag die een Accept-header opgeeft met de waarde application/vnd.adventure-works.v2+json. Het vnd.adventure-works.v1-element geeft bij de webserver aan dat versie 2 van de resource moet worden geretourneerd, terwijl het json-element aangeeft dat de indeling van de inhoud JSON moet zijn:
De code voor het verwerken van de aanvraag is verantwoordelijk voor de verwerking van de Accept-header en het zo veel mogelijk naleven ervan (de client toepassing kan verschillende indelingen opgeven in de Accept-header. In dat geval kan de webserver de meest geschikte indeling voor de inhoud kiezen). De webserver bevestigt de indeling van de gegevens in de inhoud met behulp van de Content-Type-header.
Als de Accept-header geen bekende mediatypen opgeeft, kan de webserver een antwoordbericht HTTP 406 (Niet aanvaardbaar) genereren, of een bericht retourneren met een standaard-mediatype. Deze aanpak is weliswaar de zuiverste van de mechanismen voor versiebeheer en is van nature geschikt voor FHIR referenties, dat het MIME-type van gerelateerde gegevens in links naar resources kan opnemen.
| Info | ||
|---|---|---|
| ||
Wanneer men een strategie voor versiebeheer selecteert, moet men ook de gevolgen voor de prestaties overwegen, met name opslaan in caches op de webserver. De schema's voor URI-versiebeheer is cache-vriendelijk, aangezien dezelfde combinatie van de URI-querytekenreeks telkens naar dezelfde gegevens verwijst. De mechanismen voor Header-versiebeheer en Mediatype-versiebeheer vereisen extra logica voor het onderzoeken van de waarden in de aangepaste header of de Accept-header. In een grootschalige omgeving kan het gebruik van verschillende versies van een web-API door veel clients leiden tot een aanzienlijke hoeveelheid gedupliceerde gegevens in een cache aan serverzijde. Dit probleem kan acuut worden als een client toepassing met een webserver communiceert via een proxy die opslaan in cache implementeert en die alleen een aanvraag naar de webserver verzendt als deze niet op dit moment een kopie van de aangevraagde gegevens in de cache bevat. |
Het Open API Initiative
Het Open API Initiative is gemaakt door een brancheconsortium om 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 Initiative gebracht.
Wellicht kan men het OpenAPI overnemen voor de beheer van de verschillnde 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.
...
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 kan door de volgende methoden:
- Capability Statement van de FHIR resource service. Deze methode is verplicht. In het capability statement staat de versie in het
fhirVersionveld.Code Block { "resourceType": "CapabilityStatement", "fhirVersion": "4.0.1", ... } De FHIR versie onderdeel te maken van de MIME-type als parameter in de
Content-Typeheader. Deze methode is optioneel.Code Block Accept: application/fhir+json; fhirVersion=4.0; charset=utf-8De FHIR versie in de URL van de FHIR service als pad toe te voegen in de URL. Deze methode is optioneel. Een voorbeeld voor versie
4.0.1ziet er als volgt uit:Code Block https://fhir.example.com/fhir/<domain>/4.0.0/metadata
FHIR versies vanuit de API client
De FHIR client mag gebruik maken van de fhirVersion parameter in de Content-Type of Accept header, maar is dit niet verplicht. De FHIR resource service moet deze valideren met de eigen FHIR versie, met uitzondering van een conversie scenario. Van dit laatste scenario wordt in koppeltaal geen gebruik gemaakt.
API versionering.
Ook de verdere APIs in het domein, zoals de autorisatie service, mogen in hun URL de versie van hun API verwerken. Indien dit gedaan wordt, moet dit volgens het volgende nummersysteem gedaan worden:
| Code Block |
|---|
<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