TOP-KT-002 - Basis interacties - [oud]

Beschrijving

De basis voor alle (technische) interacties in Koppeltaal 2.0. is op FHIR RESTful API gebaseerd.

De basis principes van REST

• REST geeft elke resource een ID (identifier). Alles wat identificeerbaar moet zijn, moet een ID hebben. REST noemt deze identificeerbare dingen 'resources'. Op internet is er een uniek concept voor ID's: de URL. URL's vormen een globale naam en het gebruik van URL's om de belangrijkste resources te identificeren, betekent dat ze een unieke, globale ID krijgen.
• REST is een client-server-architectuur. De server manipuleert en slaat informatie op en stelt deze op efficiënte wijze ter beschikking aan gebruikers. De client of afnemer van een dienst neemt die informatie over en toont deze aan de gebruiker en/of gebruikt deze om latere informatie verzoeken uit te voeren. Deze scheiding van taken stelt zowel de client als de server in staat om onafhankelijk verder te evolueren, omdat het hier alleen vereist wordt dat de interface hetzelfde blijft.
• REST zorgt voor een uniforme interface tussen de (systeem)componenten. Dit vereenvoudigt de architectuur, omdat alle componenten dezelfde regels volgen om met elkaar te praten. Het maakt het ook gemakkelijker om de interacties tussen de verschillende (systeem)componenten te begrijpen. Om dit goed te bereiken hebben we een aantal randvoorwaarden nodig. Zie de basis CRUD verderop.
• REST gebruikt meerdere representaties. Een representatie is een formaat waarin de gegevens worden getransporteerd tussen client-server. Met behulp van HTTP-protocollen kan een client vragen om een weergave in een bepaald formaat. REST staat meerdere representaties voor een resource toe. JSON en XML zijn de gebruikte representaties binnen Koppeltaal.
• REST is stateless. Dat betekent dat de communicatie tussen de client en de server altijd alle informatie bevat die nodig is om een aanvraag uit te voeren. Er is geen sessiestatus op de server, deze wordt volledig aan de kant van de client bijgehouden. Als toegang tot een resource authenticatie vereist, dan moet de client zichzelf bij elk verzoek authentiseren, d.m.v. een toegangstoken.

Basis interacties met een server of andere applicatie moeten volledig worden aangestuurd door hypermedia (links-URLs). De client heeft geen voorkennis van de dienst nodig om deze te gebruiken, behalve een toegangspunt (endpoint) en natuurlijk basiskennis van het mediatype van de representaties, in ieder geval voldoende om hyperlinks en linkrelaties te vinden en te identificeren.

Onderstaand interactiediagram, beschrijft een data-uitwisselingspatroon waar alle functionele interacties op gebaseerd zijn:

De FHIR Resource Provider combineert de Sink, Store en Publisher. Elke applicatie kan een combinatie van de technische actoren Source, Consumer en Subscriber implementeren.  

Technische Interacties

De URL opbouw

URL's maken het mogelijk om alle FHIR resource instanties via een netwerk te kunnen identificeren. REST legt de nadruk op een consistent definitie van deze URL's, zodat ze voor zichzelf spreken, intuïtief zijn en gemakkelijk op te bouwen zijn door applicatie instanties. Om tot een consistente manier te komen om URL's te definiëren, moeten ze zorgvuldig worden ontworpen, vandaar hier een paragraaf over de URL opbouw en het gebruik ervan.

Voordat we ingaan op de kern van de URL opbouw, wordt eerst de  verschillende onderdelen van de URL opbouw uitgelegd.
Een URL heeft de volgende opbouw : schema://domein:poort/pad?query_string. Zie ook RFC-3986.

Waar:

• Het schema definieert de contexttype van de URL, het doel en de syntaxis van het resterende deel van de URL. De software zal proberen een URL te verwerken volgens het schema en de context. Bijvoorbeeld, een webbrowser zal gewoonlijk de verwijzing naar de URL http://voorbeeld.nl:80 verwijderen door een HTTP verzoek uit te voeren aan de host op voorbeeld.nl, met poortnummer 80. Andere voorbeelden van schema namen omvatten https:, gopher:, wais:, ftp:.
• Het domein of IP-adres geeft de bestemming locatie voor de URL. Het domein koppeltaal.nl, of het IP-adres aa.bb.ccc.dd, is het adres van de website van Koppeltaal. Het domeinnaamgedeelte van een URL is niet hoofdlettergevoelig omdat DNS hoofdletters negeert: https://koppeltaal_acc.provider.nl/ en
  HTTPS://KOPPELTAAL_ACC.PROVIDER.NL/ openen beide dezelfde pagina.
• De poort is optioneel; indien deze wordt weggelaten, wordt de standaardwaarde voor het schema gebruikt. Bijvoorbeeld, http://vnc.voorbeeld.nl:5800 maakt verbinding met poort 5800 van vnc.voorbeeld.nl, wat geschikt is voor een VNC-afstandsbedieningssessie. Als het poortnummer wordt weggelaten voor een http: URL, maakt de browser verbinding op poort 80, de standaard HTTP-poort. De standaardpoort voor een https: verzoek is 443.
• Het pad wordt gebruikt om de gevraagde (FHIR) resources voor een bepaalde organisatie/zorg afnemer te specificeren en deze te vinden. Deze is wel hoofdlettergevoelig, hoewel het door sommige servers als hoofdletterongevoelig kan worden behandeld, vooral die op Microsoft Windows gebaseerd zijn. In het pad kan ook een major versie opgenomen worden zie Versiebeheer en -beleid.
  Pad voorbeeld: /zorgafnemerXYZ/v3/Patient/1234
• De query_string bevat gegevens die moeten worden doorgegeven aan software die op de server draait. Het kan naam/waarde-paren bevatten, bijvoorbeeld gescheiden door ampersands first_name=Koppel&last_name=Taal.

Belangrijk:

Bepaalde karakters zijn in de query_string NIET toegestaan. Deze MOETEN door een escape sequence, een procentteken "%" gevolgd door twee hexadecimale cijfers (0-9, A-F) die de waarde voor dat karakter (octet waarde) aangeven, vervangen worden.

Zie de volgende BNF notatie voor de query_string:

schema://domein:poort/pad?query_string

• query_string = xalphas [ + search ]
• xalpha = alpha | digit | safe | extra | escape
• alpha = a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r | s | t | u | v | w | x | y | z | A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | X | Y | Z
• digit = 0 |1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9
• safe = $ | - | _ | @ | . | & | + | -
• extra = ! | * | " | ' | ( | ) | ,
• escape = % hex hex

Dus de karakters ‘:’ , '/', '?', '#', '[', ']', ‘|’, ';'  en  '=' MOETEN in de query_string omgezet worden naar %3A , %7C en %3D, zie de escape (en asciitable.com voor translatie).

Voorbeeld:

GET https://koppeltaal_acc.provider.nl/zorgafnemerXYZ/v3/Patient?identifier=urn:oid:2.16.840.1.113883.16.3.4.2.6|KT20-116 

wordt deels ge-escape ...

GET https://koppeltaal_acc.provider.nl/zorgafnemerXYZ/v3/Patient?identifier=urn%3Aoid%3A2.16.840.1.113883.16.4.3.2.6%7CKT20-116

Content-Type

De Content-Type (HTTP) header wordt gebruikt om het mediatype (of inhoud type) van de resource aan te geven. In reacties vertelt een Content-Type-header de klant wat het content-type van de geretourneerde content eigenlijk is.

De Content-Type is een samengestelde string en bestaat uit

• het media-type (application/fhir+xml of application/fhir+json content),
• karakter encoding standaard (utf-8) en
• de gebruikte FHIR resource versie die uitgewisseld wordt (fhirVersion=4.0) .

Voorbeeld:
Content-Type

Representatie

Voor de representatie van de FHIR resources wordt JSON (application/fhir+json)of XML (application/fhir+xml)gebruikt.

JSON

• De JSON representatie voor een (FHIR) resource is gebaseerd op RFC8259
• element namen zijn hoofdlettergevoelig en UNIEK
• De volgorde van de elementen van een (resource) object is niet significant in een JSON-representatie, hoewel de volgorde binnen een array MOET worden gehandhaafd
• string elementen MOGEN NIET leeg zijn en moeten met minimaal 1 karakter gevuld zijn
• Er bestaan geen namespaces in JSON 
• JSON-elementen met '_' voor de naam van het element, worden gebruikt bij id en/of extensies, als deze aanwezig zijn. Voorbeeld:

  
  

  <birthDate id="314159" value="1970-03-30" >   <extension url="http://example.org/fhir/StructureDefinition/text">     <valueString value="Easter 1970"/>   </extension> </birthDate>

  "birthDate": "1970-03-30",   "_birthDate": {     "id": "314159",     "extension" : [ {       "url" : "http://example.org/fhir/StructureDefinition/text",       "valueString" : "Easter 1970"      }]    }

• De volgende karakters MOETEN in JSON ge-escape worden:

1. 1. backspace \b of \u0028
   2. formfeed: \f of \u002C
   3. newline: \n of \u002A
   4. carriage return: \r of \u0045
   5. tab: \t of \u0029
   6. dubbele quote:  \" of \u0022
   7. backslash: \\  of \u005C
   8. forward: \/ of  \u002F
   9. separator: \r of \u003E

2 dubbele quote voorbeelden met utf-8 karakterset : ""Iñtërnâtiônàlizætiøn""

Voorbeeld:

{
	"resourceType": "Patient",
	"contact":  [
		{
    		"name": {
                "text":"\"Iñtërnâtiônàlizætiøn\u002"
            }
		}
	]
}

• Voor meer voorbeelden zie: Json - FHIR v4.3.0 (hl7.org)

XML

• De XML representatie voor (FHIR) resources zijn vastgelegd in een basisschema "fhir-base.xsd" en definieert alle datatypes en basis infrastructuur types. Daarnaast is er een schema voor elke resource en een algemeen schema fhir-all.xsd dat alle (FHIR) resource schema's omvat. Voor schemaprocessors die niet van circulaire include houden, is er een enkel schema dat alles bevat.
• Resource en element namen zijn hoofdlettergevoelig
• Elementen moeten altijd in de gedocumenteerde volgorde verschijnen
• Wanneer een element mag worden herhaald, worden de elementen geordend en moet de technische infrastructuur in de juiste volgorde toegang hebben tot de items
• Sommige properties mogen als attributen worden gepresenteerd, waarden van primitieve typen in een 'value' attribuut, extensie-URL's in het 'url' attribuut op een extensie en de 'id' property op elementen (maar niet op resources, waarbij de resource-ID een element is)
• FHIR elementen zitten altijd in de 'http://hl7.org/fhir' namespace
• FHIR elementen en attributen zijn nooit leeg
• De volgende karakters MOETEN in XML ge-escape worden:

1. 1. ":   " of Ŗ
   2. ':   ' of Ɖ
   3. <:   &lt; of &#604;
   4. >:   &gt; of  &#625;
   5. &:   &amp; of &#38;

Toegestane karakters XML v1.0.

Char   ::=   #x9 | #xA | #xD | [#x20-#xD7FF] | [#xE000-#xFFFD] | [#x10000-#x10FFFF]/* any Unicode character, excluding the surrogate blocks, FFFE, and FFFF. */

Voorbeeld:

<Patient xmlns="http://hl7.org/fhir">
	<contact>
		<name>
        	<text value="&quot;I&#241;t&#235;rn&#226;ti&#244;liz&#230;ti#248;n&quot;"/>
        </name>
	</contact>
</Patient>

• Voor meer voorbeelden zie: Xml - FHIR v4.3.0 (hl7.org)

Resource Bundle

Elke interactie die resulteert in, of die een verzameling resources aanbiedt, wordt uitgevoerd via een resource Bundle mechanisme. Een FHIR Bundle resource is een verzameling resources die gerelateerd zijn, bijvoorbeeld het resultaat van een zoekactie, of een verzameling van historische versie van een resource.

De resource Bundle wordt beschreven in FHIR http://hl7.org/fhir/R4/bundle.html.

Response op interacties in de HTTP headers

Rationale

Doordat de basis voor alle (technische) interacties in Koppeltaal is gebaseerd op FHIR RESTful API, wordt Koppeltaal hierdoor vereenvoudigd en de zichtbaarheid van interacties wordt verbeterd door een algemene interface toe te passen.

Implicaties

Voorbeelden

Representatie

Voorbeeld JSON

{
	"resourceType": "Patient",
	"contact":  [
		{
    		"name": {
                "text":"\"Iñtërnâtiônàlizætiøn\u0022"
            }
		}
	]
}

Voorbeeld XML

<Patient xmlns="http://hl7.org/fhir">
	<contact>
		<name>
        	<text value="&quot;I&#241;t&#235;rn&#226;ti&#244;liz&#230;ti#248;n&quot;"/>
        </name>
	</contact>
</Patient>

Toepassingsgebied

FHIR-interacties

Onderbouwen

Zie Beschrijving

Eisen

Referenties

• FHIR RESTful API: http://hl7.org/fhir/R4/http.html
• FHIR Interacties gebaseerd op http://hl7.org/fhir/R4/http.html
• FHIR Patch Zie ook: http://hl7.org/fhir/R4/http.html#patch
• SMART App Launch flow volgen, zie https://www.hl7.org/fhir/smart-app-launch/app-launch.html
• Token Introspection interface: Zie https://www.hl7.org/fhir/smart-app-launch/token-introspection.html. 
• URL opbouw Zie ook RFC-3986.
• In het pad kan ook een major versie opgenomen worden zie Versiebeheer en -beleid.
• De resource Bundle wordt beschreven in FHIR http://hl7.org/fhir/R4/bundle.html
• Het verkrijgen van een id token via een autorisatie verzoek https://openid.net/specs/openid-connect-core-1_0.html#AuthorizationEndpoint

{}