FHIR - REST Operasjoner

Owned by sven.christiansen
Last updated: Nov 20, 2024
5 min read

Generelt

Alle FHIR API’er på Helsenorge støtter et subset av den fulle spesifikasjonen: http://hl7.org/fhir/http.html

  • Det skal benyttes HTTPS

  • Det støttes pr.nå. ikke versjonering av FHIR-ressurser

HTTP-headere

Når FHIR API’ene på Helsenorge kalles, skal/kan følgende HTTP header parametere benyttes:

Støttede operasjoner

Opprette/Lagre en FHIR ressurs på Helsenorge

Create - HTTP POST

Klienter kan alltid benytte “Create” for å kreere en ny ressurs på Helsenorge. Det er da Helsenorge som bestemmer ressursens id, og det er resursens (business) identifier som identifiserere ressursen på tvers av samhandlingsdomenet.

Request/response

  • Method + Url: POST [base]/[type]

  • Content-Type: En av verdiene fra generell del over

  • Body: En FHIR ressurs av type [type]

    • Dersom ressursen har en id fra før, vil denne ikke hensyntas, men Helsenorge tildeler ressursens en id. Normalt benytter Helsenorge ressursens (business) identifier også som ressursens id på Helsenorge (se under)

    • Alle ressursene som kan opprettes på Helsenorge har en “resource”.identifier. Det er denne som identifiserer en ressurs entydig mellom Helsenorge og aktørene i sektoren. Alle ressurser som sendes til Helsenorge skal ha en identifer som er en GUID, slik at den er globalt unik mellom aktørene og Helsenorge.

  • Respons:

    • OK: 201 Created. Ved suksessfull opprettelse av ressursen og påfølgende respons er Location headeren satt inneholdende logisk id, i tillegg returneres den opprettede ressursen i sin helhet (inklusiv tildelt id)

    • Feil: 400 Bad Request + FHIR OperationOutcome

Update _create on non exist - HTTP PUT

For noen av API’ene på Helsenorge tilbys create med HTTP PUT. Dette er i hovedsak i samhandlingsmønstre der ressursen finnes lagret i et et annet kildeystem, og Helsenorge kun har deler av informasjonen i ressursen lagret, og henter alle referete ressursen fra kildesystemet ved behov. I dette tilfelle bestemmer kildesystemet (klienten mot Helsenorge) ressursens id.

I de API’er der create med HTTP PUT tilbys er det alltid et krav at ressursens id er en GUID.

Request/response

  • Method + Url: PUT [base]/[type]/[id]

  • Content-Type: En av verdiene fra generell del over

  • Body: En FHIR ressurs av type [type]

    • Ressursen i body skal ha en id og denne skal være den samme som i URL’en.

    • Ressursen skal også ha en (business) identifier. Denne kan være den samme som ressursens id.

  • Respons:

    • OK: 201 Created. Ved suksessfull opprettelse av ressursen og påfølgende respons inneholder Location header for ressursen (som er den samme som URL’en i requesten).

    • Feil: 400 Bad Request + FHIR OperationOutcome

Transaction - HTTP POST

I noen API’er kan klienter benytte “Transaction” for å sende en FHIR Bundle til Helsenorge, og alle ressursene i Bundelen blir opprettet. Det er forutsatt at bundelen kun inneholder FHIR ressurser som støttes i det aktuelle grensesnitt.

Request/response:

  • Method + Url: POST [base]

  • Content-Type: En av verdiene fra generell del over

  • Body:

    • En FHIR ressurs av type Bundle av typen “transaction”(Dersom Bundle har en ressurs-ID fra før, vil denne endres)

    • Hver ressurs i Bundle SKAL etterfølges av hvilken operasjon som skal utføres. Det støttes kun HTTP POST operasjon for ressursene i bundelen, dvs. at alle ressursene i Bundelen får en ID tilordnet av Helsenorge når de opprettes.

  • Respons:

    • 200 OK + Bundle med Bundle.type = "transaction-response"

    • Feil:

Hente ut en FHIR ressurs fra Helsenorge

Read - HTTP GET

Request/response:

  • Method + Url: GET [base]/[type]/[id]

  • Accept: En av verdiene fra generell del over

  • Body: N/A

  • Respons:

    • 200 OK + FHIR-resource of [type] with resource-ID [id]

    • Feil:

      • 404 Not Found

Enkel search basert på identifier - HTTP GET

Request/response:

  • Method + Url: GET [base]/[type]?identifier=[identifier.value]

  • Accept: En av verdiene fra generell del over

  • Body: N/A

  • Respons:

    • 200 OK + Bundle med Bundle.type = "searchset” med normalt bare har en ressurs av type [type] og som har denne identifier'en. Dersom søket ikke ga noe resultat inneholder Bundelen ingen ressurser.

    • Feil:

      • 401 Not Authorized

      • 400 Bad request - Hvis man ikke støtter ressurstypen

Search - HTTP POST (_search)

Vi ønsker ikke at potensiell sensitiv informasjon (eks. innbyggers fødselsnummer) skal finnes i URL’er, derfor støttes kun POST basert search.

Request/response:

  • Method + Url: POST [base]/[type]/_search

  • Content-type: application/x-www-form-urlencoded

  • Body: [query-parameters]

  • Respons:

    • 200 OK + Bundle med Bundle.type = "searchset” med en samling av FHIR ressurser av type [type] og som tilfredsstiller søkeparameterne. Dersom søket ikke ga noe resultat inneholder Bundelen ingen ressurser.

    • Feil:

      • 401 Not Authorized

      • 400 Bad request - Hvis man ikke støtter ressurstypen

Endre en FHIR ressurs som finnes på Helsenorge

Merk! For mange av FHIR ressurser har vi på Helsenorge valgt å ikke støtte Update ved hjelp av PUT. Dette fordi mange av ressursene inngår i en workflow på Helsenorge, og Helsenorge er derfor avhengig av å selv ha “kontroll” på noen elementer i ressursen. For disse ressursene skal PATCH benyttes dersom ekstern aktør ønsker å modifisere noen elementer i en eksisterende ressurs på Helsenorge.

Patch - HTTP PATCH

Denne kan alltid benyttes for å oppdatere en ressurs som allerede er lagret på Helsenorge.

Request/response:

  • Method + Url: PATCH [base]/[type]/[id]

  • Content-Type: En av verdiene fra generell del over

  • Body: FHIRPath Patch

  • Respons:

    • 200 OK

    • Feil:

      • 400 Bad request

Update - HTTP PUT

Helsenorge aksepterer “Update” ved HTTP PUT for noen ressurser for å endre en allerede eksisterende ressurs. Dette er i UseCases der ressursen i sin helhet er en “kopi” på Helsenorge av en ressurs hvor “master” finnes hos helkseforetaket. Det vil framgå i beskrivelsen av det enkelte API/Ressurs., om det støtets “fullstendig overskriving” av ressursen med HTTP PUT.

Det støttes ikke opprettelse av ressurser ved hjelp av PUT.

Request/response:

  • Method + Url: PUT [base]/[type]/[id]

  • Content-Type: En av verdiene fra generell del over

  • Body: En FHIR ressurs av type [type]- Ressursens-ID skal være satt og den samme som er angitt i URL. ID’en skal være den som Helsenorge returnerte når ressursen ble opprettet med POST.

  • Respons:

Slette en FHIR ressurs som er lagret på Helsenorge

Delete - HTTP DELETE

I noen av løsningene på Helsenorge tillates at ekstern aktør kan slette en FHIR ressurs på Helsenorge. Dersom dette er tillatt, vil det fremgå av beskrivelsen for den aktuelle tjeneste.

Request/response:

  • Method + Url: DELETE [base]/[type]/[id]

  • Body: N/A

  • Respons:

    • 204 No Content

    • Feil:

      • 405 Method not Allowed