Page Comparison

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.

...

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

De volgende CI worden 

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

...

...

De volgende paragrafen beschrijven enkele verschillende benaderingen hoe om te gaan met verschillende versies, die allemaal hun eigen voor- en nadelen hebben.

...

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 inhoud optionele elementen toevoegt aan bestaande FHIR resources, is er mogelijk geen wijziging die problemen geeft, omdat cliënt toepassingen die deze inhoud elementen niet verwachten te zien, dit zullen negeren.

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

GET https://koppeltaal.nl/fhir/Patient/3verwacht door detoepassing: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.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 b

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.

Als het vorige voorbeeld wordt uitgebreid, als het veld is geherstructureerd in subvelden met elk onderdeel van het adres (zoals , , en ), kan deze versie van de resource worden blootgesteld via een URI met eenversienummer, zoalshttps://koppeltaal.nl/v2/Patient/3

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.

...

Het Open API

...

Iniatief

Het Open API InitiativeIniatatief 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 Initiatief gebracht.

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

...