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:

• Content-Type: Påkrevet ved POST, PUT eller PATCH. Skal ha en av verdiene: application/fhir+xml, application/fhir+json, application/json, application/xml eller  application/x-www-form-urlencoded. (Se detaljer om hver operasjon, for hvilke verdier som aksepteres).

• Authorization: Påkrevd. Skal ha verdien Bearer <aksesstoken>. (Se 01 - Sikkerhetsmodell og Helsenorge sikkerhetstjeneste )

• Accept: Frivillig. Dersom satt, skal ha en av verdiene: application/fhir+xml, application/fhir+json, application/json eller application/xml. (Dersom ikke satt vil responsen sin Content-Type være satt til application/fhir+json)

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.

  • 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. For de fleste ressursene er denne i implementasjonsguiden definert å skulle være 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 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:

    • 400 Bad Request + Bundle med et sett FHIR OperationOutcome

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:

  • 200 OK

  • Feil:

    • 400 Bad Request + FHIR OperationOutcome

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