Document toolboxDocument toolbox

TOP-KT-002a - FHIR Resource Service interacties

 Versiegeschiedenis
VersieDatumStatusWijzigingen
0.1.2

conceptImplementationGuide toegevoegd
0.1.1

 

conceptOnderdeel encoding toegevoegd
0.1.0

 

concept

Beschrijving

Om Resources binnen domeinen uit te wisselen maakt Koppeltaal gebruik van een FHIR resource service. Dit document beschrijft welke interacties er ondersteund worden.

Overwegingen

Koppeltaal maakt gebruik van een FHIR resource service. Deze service kan middels de FHIR RESTful API specificaties benaderd worden. Applicaties in een domein (applicatie-instanties) kunnen na authenticatie toegestane acties uitvoeren op de FHIR resource service. Geautoriseerde applicatie-instanties kunnen vervolgens deze informatie ophalen en waar nodig (en mogelijk) bijwerken. De resources dienen op een eenduidige manier aangemaakt en uitgewisseld te worden. Zo kunnen applicaties in het domein goed samenwerken. Ook moeten er uitbreidingen op de standaard gemaakt worden om bijvoorbeeld geautomatiseerd te voldoen aan wetgeving.

Toepassing en restricties

Profielen

Om te waarborgen dat iedereen dezelfde taal spreekt, en alle benodigde informatie voor iedereen aanwezig is, vereist Koppeltaal het gebruik van profielen. Elk toegestane resource heeft een eigen profiel. Een profiel gebruikt een StructureDefinition resource als datastructuur. Deze resource beschrijft welke eigenschappen een resource heeft, en bijvoorbeeld ook wat de kardinaliteit van elk veld is. De officiële Koppeltaal profielen zijn hier te vinden: https://simplifier.net/Koppeltaalv2.0/~resources?category=Profile&fhirVersion=R4.

De StructureDefinition resources dienen door de FHIR resource service ingeladen te worden. Applicatie-instanties mogen deze niet zelf aanmaken of bewerken.

Validatie

Zie TOP-KT-010 voor meer informatie over de validatie.

Capabilities

De FHIR resource service beschrijft de functionele mogelijkheden in de CapabilityStatement. Zie /wiki/spaces/K2/pages/17531608 en https://www.hl7.org/fhir/r4/capabilitystatement.html voor meer informatie.

ImplementationGuide

De ImplementationGuide beschrijft de versie, release datum e.d. van de Koppeltaal Profielen. Zie ook Koppeltaal ImplementationGuide voor meer Informatie. 

FHIR RESTful API

De FHIR RESTful API biedt een groot scala aan functionaliteiten. De specificatie bevat ook optionele functionaliteiten. Binnen Koppeltaal is gekozen wat wel en niet ondersteund wordt:

Instance Level Interactions


OndersteundRemark
readRead the current state of the resource✓
conditional readRead the current state of the resource if modified since of matches ETag✓
vreadRead the state of a specific version of the resource✓
updateUpdate an existing resource by its id (or create it if it is new)âš If-Match header verplicht
conditional updateAllows a client to update an existing resource based on some identification criteriaâš Trial use fase
patchUpdate an existing resource by posting a set of changes to it✗Wordt mogelijk in een toekomstige versie toegevoegd
conditional patchAllows a client to patch an existing resource based on some identification criteria✗
deleteDelete a resourceâš Bij voorkeur gebruik maken van een end-of-life status i.p.v. een delete
conditional deleteAllows a client to delete an existing resource based on some selection criteriaâš Trial use fase
historyRetrieve the change history for a particular resource✓
Type Level Interactions
OndersteundRemark
createCreate a new resource with a server assigned id✓
conditional createAllows a client to create a new resource only if some equivalent resource does not already exist on the server.âš Trial use fase
searchSearch the resource type based on some filter criteriaâš Zie ondersteunde search result parameters
search pagingSupport paging for the results of a search or history interaction✓
historyRetrieve the change history for a particular resource type✓
Whole System Interactions
OndersteundRemark
capabilitiesGet a capability statement for the system✓
batch/transactionUpdate, create or delete a set of resources in a single interaction (FHIR Bundle)✗
historyRetrieve the change history for all resources✗
searchSearch across all resource types based on some filter criteria✗


ConnectionType

Aangezien we met een FHIR RESTFull API te maken hebben is de waarde van Endpoint.connectionType gefixed op hl7-fhir-rest. 

Mime-Type

Ook is er een keuze gemaakt welke MIME-types worden ondersteund. Het MIME-type MOET middels de Content-Type header meegegeven worden wanneer er een resource naar de FHIR resource service gestuurd wordt.

De Accept header MAG gebruikt worden, hiervoor gelden de volgende regels:

  • Indien er geen Accept header wordt meegegeven MOET de FHIR resource service uitgaan van de standaard MIME-Type ( application/fhir+json ).
  • Indien er een Accept wordt meegegeven die voortkomt in de tabel hieronder MOET deze gebruikt worden.
  • Indien er een Accept header wordt meegegeven die niet voorkomt in de tabel hieronder heeft de FHIR resource service een aantal opties, FHIR resource service MOET een van deze opties kiezen:
    1. De FHIR resource service kan welwillend (lenient) gaan met het MIME-Type en een match proberen te maken door bv. application/json te accepteren als application/fhir+json.
    2. De FHIR resource service kan een HTTP status code 400 (Bad Request)  of 415 (Unsupported Media Type)  terugsturen, de eerste als de MIME-Type onbekend is (bv. application/fhi+xml), de laatste als de MIME-Type wel bekend is, maar niet ondersteund wordt (bv. application/pdf). Welke MIME-Types bekend of onbekend zijn, bepaalt de FHIR resource  service zelf.
    3. De FHIR resource service kan de standaard MIME-Type gebruiken.
MIME-typeGeïmplementeerdRemark
application/fhir+json✓De standaard MIME-Type
application/fhir+xml✓De xsd schema’s voor de validatie dwingen een specifieke volgorde af (xs:sequence)
application/fhir+turtle✗

De MIME-Type in de Content-Type header MAG gepostfixed worden met de FHIR version.

Correcte voorbeelden zijn:

  1. application/fhir+json; fhirVersion=4.0

  2. application/fhir+json

ens het onderdeel: TOP-KT-014 - Versiebeheer en -beleid.

Character encoding

Voor zowel application/fhir+xml  en application/fhir+json gaat FHIR er van uit dat de encoding utf-8 is, de encoding mag dus op verschillende plekken worden meegegeven, in dat geval ZOU de encoding utf-8 zijn. Indien er een andere encoding wordt meegegeven MAG de FHIR resource service een a) foutmelding geven in het 4xx segment of b) de encoding accepteren en de inhoud naar utf-8 converteren.

Correcte voorbeelden zijn:

  1. application/fhir+json; fhirVersion=4.0; charset=utf-8

  2. application/fhir+xml; fhirVersion=4.0

  3. application/fhir+json

  4. application/fhir+xml; charset=utf-8

De FHIR resource service MOET de FHIR resources aanbieden in utf-8  encoding, zowel voor application/fhir+json  als application/fhir+xml, ook als dezelfde resource origineel in een andere encoding is aangeboden. 

Character escapes

Van tekst in zowel XML als JSON dienen bepaalde tekens specifiek geëncodeerd te worden. Dit heeft te maken met het specifiek formaat en is onderdeel van de specificatie van het formaat. Het wordt in Koppeltaal sterk aangeraden gebruik te maken van utf-8  als het gaat op speciale tekens (é, ö, ï) en NIET van formaat specifieke escapes (é, ö ï), XML unicode references (&#00C9 , &#00D6   &#00EF;) of JSON unicode reference (\u00C9, \u00D6, \u00EF).

Xml Syntax

De xml syntax wordt hier beschreven. Praktisch zijn de volgende escapes van toepassing:

Symbol (name)

Escape Sequence

< (less-than)

&#60; or &lt;

> (greater-than)

&#62; or  &gt;

& (ampersand)

&#38; or &amp

' (apostrophe or single quote)

&#39; or &apos

" (double-quote)

&#34; or &quot

JSON syntax

De JSON syntax wordt hier beschreven. Praktisch zijn de volgende escapes van toepassing:

Symbol (name)

Escape Sequence

Newline

\n or \u002A

Carriage return\r or \u0045
Form feed\f or \u002C
Backspace\b or \u0028

Tab

\t or \u0029

" (double-quote)

\" or \u0022

\ Backslash\\ or \u005C


Update

Koppeltaal forceert het gebruik van de If-Match header. Dit waarborgt dat een Update altijd gebaseerd is op de laatste versie. Zo wordt de kans op dataverlies geminimaliseerd. Zie https://www.hl7.org/fhir/r4/http.html#concurrency voor meer informatie.

Delete

Koppeltaal maakt bij voorkeur geen gebruik van een DELETE request. Wanneer data niet meer gebruikt dient te worden, dient dit opgelost te worden middels een status. Zie Levenscyclus van een FHIR Resource voor meer informatie. Een DELETE request wordt wel ondersteund, maar zou in normaal gebruik van Koppeltaal niet voorkomen. Om die reden krijgen de applicaties in het domein de DELETE rechten niet, de DELETE operatie blijft van toepassing in beheer en migratie scenario's.

Recht op vergetelheid

In een aantal gevallen mag een gebruiker aan een organisatie vragen om alle (historische) gegevens, van die gebruiker, uit hun systeem te verwijderen.

Voor het fysiek verwijderen van resources hebben sommige FHIR Resource Providers een $expunge functionaliteit geïmplementeerd. Deze functie verwijdert alle versies van een resource uit de FHIR Store.

De $expunge operatie is echter GEEN STANDAARD (FHIR RESTfull) operatie, en moet apart geïmplementeerd worden voor de FHIR Store. Deze operatie mag alleen op instance-level aangeroepen worden.

If-Match delete

Tijdens een delete wordt de If-Match header niet afgedwongen. Functioneel kan een FHIR FHIR resource service dit ondersteunen, hoewel niet beschreven in de FHIR specificatie. Het is aan de uitvoerende partij om te bepalen of het belangrijk is dat een delete gebaseerd is op de versie. Bijvoorbeeld: Een eindgebruiker kan a.d.h.v. de gegevens in een GUI een object beoordelen, en verwijderen als het een bepaalde state bevat. In dit geval is het wijs om een If-Match toe te voegen. Wanneer een systeem een batch aan resources wilt verwijderen, ongeacht de state, maf de If-Match header weggelaten worden.

Conditional Create, Conditional Update en Conditional Delete

Deze functionaliteiten zijn in de “trial use” fase. Dit houdt in dat het beproefd wordt. De implementatie wordt geëvalueerd en in een toekomstige versie pas gereviewed. Er is dus een grote kans dat deze functionaliteiten in de toekomst anders zullen gaan werken. Wel zijn deze functionaliteiten geïmplementeerd. Maak enkel gebruik van deze functionaliteiten indien er bereidheid is hier later aanpassingen in door te voeren.

Links naar gerelateerde onderwerpen

BeschrijvingLinkOpmerking
FHIR RESTful API documentatiehttps://www.hl7.org/fhir/r4/http.html
FHIR concurrency met If-Matchhttps://www.hl7.org/fhir/r4/http.html#concurrency
If-Match enforce code voorbeeldhttps://github.com/Koppeltaal/Koppeltaal-2.0-FHIR-HAPI-Server/blob/master/src/main/java/ca/uhn/fhir/jpa/starter/koppeltaal/interceptor/EnforceIfMatchHeaderInterceptor.javaDeze code filtert ook PATCH requests en Bundles. Deze worden binnen Koppeltaal niet gebruikt.
Voorbeelden van alle Resources in JSON en XMLhttps://simplifier.net/Koppeltaalv2.0/~resources?category=Example&fhirVersion=R4
FHIR search specificatiehttps://www.hl7.org/fhir/r4/search.html
FHIR paginatiehttps://www.hl7.org/fhir/r4/http.html#paging