Een resource instantie creëren

Levert een payload op. In de FHIR specs staat dat de server zelf bepaalt of de volledige resource instantie wordt geretourneerd. 

Levert alleen header informatie, om te voorkomen dat bv bij het aanmaken van een grote hoeveelheid FHIR resources alle aangemaakte resources in de response komen, een vragende applicatie kan zelf bepalen of het response gevuld moet zijn, mbv de parameters ‘prefer’ en de waarde ‘return’, zoals beschreven in de FHIR specs.

Voor de leverancier is dit wel belangrijk, zodat ze altijd alle header informatie moeten uitlezen en verwerken voor de status, versie en locatie (url) van de resource instantie.

Een resource instantie verwijderen

Bij de referentieomgeving  wordt een HTTP200 met OperationOutcome ‘successfully deleted ….’ geretourneerd.

De OperationOutcome is niet gespecificeerd bij een geslaagde operatie en bij een verwijdering van een resource instantie verwacht je geen payload in een response.

Wordt een HTTP 204 geretourneerd

Als een operatie goed wordt uitgevoerd, hoeft alleen een HTTP status code geretourneerd te worden. Alleen bij een fout MOET er een OperationOutcome geretourneerd worden.

Na het succesvol verwijdering van een resource instantie, MOET de server ofwel een 200 OK retourneren, als het antwoord een payload bevat of een 204 No Content with no response payload.

Het makkelijkst is om een HTTP 204 te retourneren, omdat de server dan geen OperationOutcome hoeft te structureren, waar geen specificaties van zijn.

Ondersteuning van basis interacties

Bij de referentieomgeving wordt ook de patch en conditionele operaties ondersteund.

→ Functie is inmiddels verwijderd uit de documentatie.

Voorziening ondersteunt niet de patch en conditionele operaties.

FHIR heeft de patch en conditionele operaties op trial (proef) staan totdat er meer ervaring is opgedaan met het gebruik ervan. De status (wijziging) zal worden beoordeeld in toekomstige versies van FHIR.

Advies is om ze nu niet te gaan gebruiken in Koppeltaal zolang de status op trial staat.

Header verschillen

• ACCEPT niet aanwezig. 

• HAPI accepteerde foute Content_Type. Voorbeeld: application/json 

• 406 Not Acceptable. HTTP fout bij achterwege laten van ACCEPT.

• 415 Content_type not supported. HTTP fout  bij verkeerde content_type. 

 We ondersteunen voor de Content_Type:

• XML: application/fhir+xml

• JSON: application/fhir+json

Voor zoekopdrachten (search)

• application/x-www-form-urlencoded

Carriage returns in een response

Levert soms response geformatteerd op. Niet altijd ruwe data.

Levert elke response als ruwe data op. M.b.v. een '_pretty=true' parameter kan de data geformatteerd worden, afhankelijk van XML of JSON. Probleem hierbij is de validatie meldingen waar alle foutmeldingen refereren naar regel 1.

Moet de leverancier wel van bewust zijn.

Het gebruik van de foutmelding 409/412 conflicten bij wijzigingen

Geeft bij conflicten een 409 terug

Geeft 412 terug

Wat is het verschil?

• 409. De server heeft de bron gelockt waardoor wijziging niet mogelijk is. Ook wel pessimistische locking genoemd. Kwam veel voor bij KT 1.3.x. Vanwege messaging en record locking in database. Werden berichten uitgewisseld.

• 412. Pre-conditie faalt. Als de versie-id in de If-Match niet overeenkomt. Ook wel optimistiche locking genoemd. Deze melding kan bij (FHIR) REST API PUT/PATCH-verzoeken voorkomen. Deze zou juist bij KT 2.0 voorkomen, omdat deze op REST API gebaseerd is ipv messaging.

Paging

Ondersteunt Offset paging met parameter '_offset'. Is geen standaard FHIR, extra uitbreiding van HAPI. Client bepaalt navigatie. 

Maakt gebruik van '_count' en navigatie links in Bundle. Standaard FHIR, maar is geen MUST maar een SHOULD voor ondersteuning van de server. Server bepaalt hier de navigatie.

Als de FHIR Resource Provider (of FHIR Store) geen Paging ondersteunt, kan er niet door een client applicatie gedoseerd door de aangeleverde resources genavigeerd worden.

Bij ondersteuning van Paging, zou de client applicatie de navigatie linkjes moeten vertalen in Navigatie Buttons op de user interface (scherm).

Authorization code flow bij OAuth2

Bij opvragen van het Access_Token wordt het Access_Token leeg gelaten. NIET CONFORM SMART Launch/OAuth2 SPECS - authorization code flow. zie:  https://datatracker.ietf.org/doc/html/rfc6749#section-4.1 

Door Remco Schaar bevestigd.

Gegenereerde sleutel paren

Zowel HAPI als

KT-voorziening MOETEN de volgende algoritmes kunnen ondersteunen:

RS256, RS384, en RS512 en ES256, ES384, en ES512. 

→ Zie specs TOP-KT-020.

Deze wordt in de JWT header meegegeven. Zie "alg".

Verlopen access_token

HAPI retourneert HTTP401

"diagnostics": "Unauthorized" 

retourneert HTTP401

"diagnostics": "security/suppressed",

 "details": {

                          "text": "security/suppressed"

Zolang ze dezelfde HTTP 401 terug geven, betekent dat er authenticatie is vereist voor die interactie die geprobeerd is. Eis:

• De server MOET een OperationOutcome retourneren als de REST-interactie of bewerking is mislukt

• Hierin MOET informatie staan wat de reden is waarom het fout is gegaan

• Bij autorisatie fouten moet de voorziening (server) zo min mogelijk informatie weggeven. Het retourneren van te veel informatie kan details over de toegang blootleggen die NIET naar cliënten gecommuniceerd mogen worden.

Opmerking de voorziening (server)  bepaalt zelf de content van de OperationOutcome.

Profielen

Meta.profile MOET gevuld worden met Koppeltaal profiel.

Meta.profile mag gevuld worden. Indien niet gevuld, wordt er teruggevallen op FHIR R4.

We gaan bij Koppeltaal 2.0 afdwingen om het Meta.profile te vullen met een profiel bij zowel POST als PUT. Indien NIET gevuld een HTTP 422 met melding "No matching profile" retourneren. 

Diakritische tekens

HAPI gaat goed om met diakritsche tekens

Voorziening heeft problemen met bepaalde diakritische tekens in XML. Resulteert in foutmelding HTTP 403. Diakritische tekens in JSON worden wel goed verwerkt.

Is opgelost.

UTF-8 is een methode om Unicodes in bytes te coderen. Zie ook beschrijving: TOP-KT-002 - Basis interacties - [oud] voor UTF-8, XML en JSON.

XML Sequence

Indien de elementen van een FHIR resource in een andere XML volgorde worden aangeboden, dan is vastgelegd in de StructureDefinition (of baseDefinition) genereert HAPI de melding 'out of order'

Voorziening toont (of her rangschikt) de element van een FHIR resource  in de juiste sequence, zoals vastgelegd is in de StructureDefinition (of baseDefinition) en geeft dus niet de melding 'out of order'

Elementen in de StructureDefinition (de FHIR profiel definities) MOETEN in dezelfde volgorde staan als de baseDefinition van de resource (XML Schema van een FHIR resource). 

Zie voor meer informatie de FHIR specificaties op http://hl7.org/fhir/R4/structuredefinition.html#interpretation

Het is dus niet mogelijk om de volgorder hiervan te wijzigen.

Indien de FHIR resource in JSON wordt gepresenteerd, maakt de volgorde van de velden (elementen) niet uit 

Search

• De return Bundle heeft een element _total dat het aantal gevonden resources geeft dat overeenkomt met de zoekparameters.

In sommige gevallen wordt er het element _total in de Bundle NIET teruggegeven. Onduidelijk is wanneer wel of niet

Altijd wordt het element _total teruggeven

Parameter _total=accurate wordt door Intersystems niet ondersteund.

De parameter _total heeft de status trial-use bij de FHIR community, in afwachting van ervaring in de echte wereld van het gebruik ervan. Zou wel graag een consistente ervaring willen opdoen.

• Servers MOETEN paging ondersteunen voor de resultaten van een Search interactie, en als ze dat doen, MOETEN ze voldoen aan deze methode (aangepast van RFC 5005 (Feed Paging and Archiving) voor het verzenden van vervolglinks naar de client bij het retourneren van een Bundle (bijv. geschiedenis en zoeken). Als de server dit niet doet, is er geen manier om door te gaan met oproepen.

Zie:

The feed documents in a paged feed are tied together with the following link relations: 

• "first" - A URI that refers to the furthest preceding document in a series of documents. 

• "last" - A URI that refers to the furthest following document in a series of documents.

• "previous" - A URI that refers to the immediately preceding document in a series of documents.

• "next" - A URI that refers to the immediately following document in a series of documents.

Paged feed documents MUST have at least one of these link relations present, and should contain as many as practical and applicable.

Er wordt bij een search geen "last" link teruggegeven, wel "self", "next" en "previous"

Voldoet aan RFC5005. Geeft alle link relaties terug.

Een server KAN de klant informeren over het _total aantal resources dat is geretourneerd door de interactie waarvoor de resultaten worden opgeroepen met behulp van de Bundle.total. Zie vorige item. Via de "last" link kan men meteen naar het laatste record gaan. Heeft veel voordelen als het _total groot is. Graag ook "last" link retourneren bij een Search.

Het zoeken op _elementen (velden met waarden) in een resource instantie, zoals door FHIR beschreven.

Voorbeeld zoeken op identifier en active:

GET http://hapi.fhir.org/baseR4/Patient?_elements=identifier,active

Wordt ondersteund door HAPI

Oplossing voor _elements wordt geïmplementeerd in versie 2022.2 (huidige versie is 2022.1). Probleem hertesten als versie uitgebracht is (Jira IF-2597)

Is opgelost.

Koppeltaal wacht op nieuwe versie van InterSystems (Jira IF-3171)

Maximum in respons.

Een zoekopdracht levert maximaal 40 records op.

Een zoekopdracht levert maximaal 100 records op.

Gebruik paging voor ophalen niet getoonde respons.

AuditEvent:

Er zijn veel kleine verschillen. Bijvoorbeeld de notering van datum/tijd, en velden de niet verplicht zijn, die de ene wel veld en de ander niet. Hiernaast worden de belangrijkste verschillen genoemd.

• Bij outcome<>0 bevat OutcomeDesk de foutmelding uit OperationOutcome.

• Bij outcome<>0 bevat entity.type.code OperationOutcome.

• Entity.what.reference (bij outcome=0): resource/id/_history/versie

• Entity.query: bij alle acties met outcome=0. (Is niet correct)

• Action=R bij Search en Metadata.

• Entity.what/type/query worden bij Search voor elk gevonden item gegeven. (Is niet correct)

• Entity.what (bij delete): niet aanwezig. (Is niet correct)

• Entity.description: niet aanwezig.

• Bij outcome<>0 bevat Contained de foutmelding uit OperationOutcome. In entity.what staat dan een 'interne referentie' naar Contained.

• Bij outcome<>0 zijn er 2 entity.type.code. 1 met OperationOutcome. 1 met resource.

• Entity.what.reference (bij outcome=0): baseUrl/resource/id/_history/versie

• Entity.query: Alleen bij 'search' acties.

• Action=E bij Search en Metadata.

• Entity.what/type/query is bij Search niet aanwezig. De query geeft aan wat er gezocht werd.

• Entity.what (bij delete): bevat resource/id.

• Entity.description: "Succesfully processed request".

• Voor CapabilityStatement en Conformiteit worden geen AuditEvents aangemaakt.

AuditEvent notifcatie

Indien notificatie niet afgeleverd kan worden, zorgt HAPI ervoor dat dit nog 20 keer geprobeerd wordt. Voor elke poging wordt een AuditEvent gelogd. Dit retry-mechanisme is geen onderdeel van de standaard.

Abonneren/notificeren:

• Status 'requested' wordt omgezet naar 'active', maar daarvoor wordt een nieuwe versie van de resource gemaakt.

• Channel.type = rest-hook wordt niet afgedwongen.

• Search narrowing wordt pas bij ophalen gegevens toegepast.

• Status 'requested' wordt direct omgezet naar 'active'.

• Channel.type = rest-hook wordt afgedwongen.

• Aan criteria wordt automatisch de resource-origin toegevoegd als autorisatie daar aanleiding toe geeft.

• AuditEvent.entity.what bevat voor notificaties (Transmit) de referentie naar de Subscription op basis waarvan de notificatie is verstuurd.

• AuditEvent.entity.network wordt bij notificaties gevuld met Subscription.channel.endpoint.

• Notificatie werkt niet wanneer Subscription.criteria alleen de resource bevat, bijv.: "criteria": "Task?". Dit is ook niet de bedoeling, maar het aanmaken hiervan moet nog afgevangen worden. Is als bevinding opgevoerd.

Extra specificaties

KT-voorziening omgeving zijn te vinden in document: Technical Documentation for Koppeltaal 2 Server. Te vinden op: Specificaties Itzos.

Search met foute parameter

Geeft HTTP400 met error melding.

Geeft HTTP200 met in respons error melding en de records obv search excl. foute paremeter.

Beide responses zijn conform FHIR.

Updaten resource Device

Is voor geautoriseerden mogelijk

Is geheel afgeschermd i.v.m. risico's voor werking applicatieinstantie. Respons HTTP400, diagnostics:<HSFHIRErr>InteractionNotSupported, details: text:Interaction 'update' is not supported for resource type 'Device'.

Conformiteit

Is conform specificaties

Parameter scopes_supported: laatste 2 items ziijn "user/*.crud" en "user/*.crud?resource-origin=" ipv 'system/....

De waarde "system/*.cruds" of "user/*.cruds" is niet betekenisvol voor de gebruiker omdat er geen access_token wordt teruggegeven uit de SMART-on-FHIR token request.

Resource-origin in Post en Put

In Post mag geen resource-origin worden meegegeven. Dit geeft een foutmelding.

In Put mag een resource-origin worden meegegeven, maar deze wordt toegevoegd indien niet aanwezig. Een foute resource-origin geeft een foutmelding.

Het in Post meegeven van een (foute) resource-origin wordt genegeerd. Resource wordt aangemaakt.

In Put mag een resource-origin meegegeven worden. Indien deze niet correct is, wordt deze genegeerd en de respons voorzien van een correcte resource-orgin.

Patient.name.use / Practitioner.name.use

Is verplicht volgens profiel, maar wordt bij ontbreken ervan in de Referentieomgeving, niet als fout gegeven bij een Xml bericht.

Zowel voor Json als Xml wordt een foutmelding gegeven als het element ontbreekt.

Device

• DeviceId is nieuw uitgegeven UUID.

• Het is mogelijk om een nieuw Device aan te maken zelfde ClientId en een Device te wijzigen.

• DeviceId is gelijk aan ClientId.

• Hiet is niet mogelijk om een 2e Device aan te maken voor zelfde clientId. Geeft HTTP403 Forbidden, met melding: "Key not unique: HSFHIR.X0006.R.Rsrc:KeyIdx:^HS .Local.FHIRServEC11.ResourceI(\"KeyIdx\",\"Device/<id>\")"

• Het is niet mogelijk om een Device te wijzigen. Dit geeft een HTTP400 Bad Request, met melding: "Interaction 'update' is not supported for resource type 'Device'."

Volgorde authenticatie/autorisatie

In de referentieomgeving wordt eerst volgens spec de autorisatie en authenticatie uitgevoerd, voordat een eventuele foutmelding als HTTP422 gegeven wordt.

Een foutmelding als HTTP422 wordt eerst gegeven, en na oplossen pas een HTTP403 indien niet geautoriseerd. Dit is omgekeerd t.o.v. de Referentieomgeving en niet volgens specs (topic12-eis009).

Besloten is om de volgorde van de voorziening niet aan te passen.  Software maakt het op deze manier ook mogelijk om batch/bulk verwerking toe te kunnen passen. Bovendien is aanpassing zeer complex, terwijl de volgorde niet tot grote problemen kan leiden.

Autorisatie / referentiecontrole

Hiernaast genoemde controle komt niet voor in de Referentieomgeving.

Het is niet mogelijk om een create of update van een resource uit te voeren als deze een referentie bevat voor een resource waar betreffende applicatie geen leesrechten voor heeft.

Subscription parameter probleem.
Dit probleem komt voor bij alle subscriptions; Task, Patient, Practitioner, etc.

KTL-8

Het is niet mogelijk om active=true te gebruiken als parameter.
bijvoorbeeld:
https://acc21.koppeltaal.nl/api/v1/adhdcentraal-acceptatie/fhir/r4/Patient?_lastUpdated=gt2023-11-23T15:18:19.298829&_sort=_lastUpdated&active=true

Het gebruik van active=1 werkt wel

Het zoeken op active=0 geeft geen resultaat.

Dit is opgelost in een volgende versie van Intersystems Iris en zal bij de eerst volgende upgrade worden opgelost.