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.Hoewel het bijwerken van de Koppeltaal interfaces 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.

...

 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

...

 ],
    "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.

Als het vorige voorbeeld wordt uitgebreid, met een verplicht element zoals bijvoorbeeld "gender", kan deze nieuwe versie van de resource worden blootgesteld via een URI met eenversienummer, zoals https://koppeltaal.nl/fhir/v2/Patient/61 

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

Aangezien de aanvraag de Major versienummer bevat, is het handig om het volledige versienummer op te geven in de response headers voor elke (interactie) aanvraag. Deze (response header) informatie kan vervolgens worden gebruikt voor logging, foutopsporing of auditdoeleinden.In gevallen waarin een tussenliggende (netwerk) component een foutmelding retourneert (bijvoorbeeld een reverse proxy die toegangsbeleid afdwingt), kan het versienummer worden weggelaten.Het versienummer moet worden geretourneerd in een HTTP-responsheader met de naam API-Version (hoofdlettergevoelig) .

Voorbeeld van een response header: API-versie: 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.

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 cliënt toepassing kan verschillende indelingen opgeven in deAccept-header. In dat geval kan de FHIR Resource Provider de meest geschikte indeling voor de inhoud kiezen). De FHIR Resource Provider bevestigt de indeling van de gegevens in de inhoud met behulp van de Content-Type-header.

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.

...