Felles definisjoner, tolkninger og krav

Denne seksjonen beskriver essensielle definisjoner og tolkninger som brukes i HelseAPI IG.

Konformitetsverbene som benyttes i integrasjonsguiden er definert i konformitetsreglene for FHIR. Følgende norske oversettelser er benyttet for verbene:

• SKAL (SHALL)

• SKAL IKKE (SHALL NOT)

• BØR / BØR IKKE (SHOULD / SHOULD NOT)

• KAN (MAY)

Felles klinisk datasett - Dataelementer

Må støttes (mustSupport)

I konteksten av HelseAPI SKAL mustSupport på ethvert dataelement tolkes som følger:

• HelseAPI tjenere SKAL inneha kapabilitet til å inkludere dataelementet som en del av forespørselen som spesifisert av HelseAPI tjener kapabilitetserklæring.

• HelseAPI klienter SKAL inneha kapabilitet til å prosessere ressursinstanser som inneholder dataelementet uten å generere en feilmelding eller forårsake en applikasjonsfeil. Med andre ord HelseAPI klienter BØR inneha kapabilitet for å kunne vise dataelementene for menneskelig bruk, lagring eller andre hensikter.

• I situasjoner der informasjon om et bestemt dataelement ikke er tilstede, og årsaken til fravær er ukjent, SKAL IKKE HelseAPI tjenere inkludere dataelementet som en del av responsen.

• Ved forespørsel mot HelseAPI tjenere SKAL HelseAPI klienter tolke manglende dataelementer for en ressursinstans som at data ikke er tilstede i HelseAPI tjenerens system.

• MERK: Lesere av disse dokumentene rådes til å ha en forståelse om FHIR terminologi, FHIR RESTful API, FHIR datatyper, FHIR søk og FHIR Resource formatet før de implementer HelseAPI kravene.

Referanser i HelseAPI profilene

Mange av profilene i denne guiden har referanser til andre FHIR ressurser som også er HelseAPI profiler. Disse er definert i de formelle profildefinisjonene. For referanser der det ikke formelt er definert en HelseAPI profil BURDE den refererte ressursen være en HelseAPI profil dersom denne eksisterer.

Syntaks leseoperasjoner

Interaksjoner er definert med følgende syntaks:

• HTTP-verbet GET brukes ved lesing av en ressurs

• Innhold omkapslet med [] er påkrevet  og erstattes med den nødvendige strengen

  • base: tjenestens rot-URL (f.eks: "https://fhir-open-api-r4.smarthealthit.org")

  • Resource-Type: typenavnet til ressursen (f.eks: "Patient")

  • id: den logiske identifikatoren til ressursen (f.eks: "504202")

• Innhold omkapslet med {} er valgfritt

  • parameters: URL-parametere som definert for den spesifikke interaksjonen (f.eks: "?_format=xml")

For mer informasjon se FHIR RESTful API.

Syntaks søkeoperasjoner

I den simpleste form utføres et søk ved en GET-operasjon i RESTful-rammeverket:

I det ovenstående eksemplet på et RESTful-søk er parameterne et sekvenspar med name=[value] kodet i URL-en. Søkeparameterne er definert pr. ressurs. Se FHIR søk for mer informasjon vedrørende søk.

Syntaks for søk som er begrenset til en pasient

Det er flere potensielle muligheter å søke etter ressurser som er assosiert med en spesifikk pasient avhengig av kontekst og implementasjon. Følgende søk vil ende opp med det samme resultatet:

1. En eksplisitt angitt pasient ved bruk av "patient" parameteren som begrenser resultatet innenfor den ressurstypen det søkes på til den angitte pasienten.

   • GET [base]/[Resource-type]?patient=504202{&otherparameters}

   • Det er flere variasjoner av denne syntaksen:

     • GET [base]/[Resource-type]?subject=[id]{&otherparameters}

     • GET [base]/[Resource-type]?subject:Patient.identifier=[system]|[code]

     • GET [base]/[Resource-type]?subject=Patient/[id]{&otherparameters}

     • GET [base]/[Resource-type]?subject._id=[id]{&otherparameters}

     • GET [base]/[Resource-type]?subject:Patient=[id]{&otherparameters}

     • GET [base]/[Resource-type]?subject:Patient=Patient/[id]{&otherparameters}

     • GET [base]/[Resource-type]?subject:Patient=[https://%5Burl%5D/Patient/id]{&otherparameters}

     • GET [base]/[Resource-type]?subject:Patient._id=[id]{&otherparameters}

     • GET [base]/[Resource-type]?patient:Patient=[https://%5Burl%5D/Patient/id]{&otherparameters}

     • GET [base]/[Resource-type]?patient:Patient.identifier=[system]|[code]

2. Pasienten KAN være en implisitt del av konteksten, slik som ved bruk av SMART. I disse tilfellene kan pasient-parameteren utelates:

   • GET [base]/[Resource-type]{?otherparameters}

Søk på tvers av plattformer

Det er ikke et krav om at HelseAPI tjenere skal støtte eksterne URL-er som går på tvers av deres systemmiljø(er).

Veiledning på begrensning av antall resultater ved søk

For å kunne begrense antall søkeresultater som returneres i hvert enkelt kall, kan serveren velge å returnere resultatene som en serie med sider. Søkeresultatet inneholder ett sett med URL-er som klienten kan benytte når den gjør en forespørsel om flere sider fra søkeresultatet, for mer informasjon se FHIR paginering.

Håndtering av versjonskonflikter

Tapte oppdateringer der to klienter oppdaterer den samme ressursen, og nummer to skriver over endringene til nummer én kan unngås ved å bruke en kombinasjon av headerene ETag og If-Match.

For å støtte oppunder håndtering av versjonskonflikter SKAL servere alltid returnere en ETag:

ETag SKAL være identisk med versjonsidentifikatoren for ressursen på serveren. (Burde vi si noe om formatet? Spesifikasjonen sier: Servers are allowed to generate the version id in whatever fashion that they wish, so long as they are valid according to the id data type, and are unique within the address space of all versions of the same resource.)

Ved oppdatering av en ressurs SKAL klienten angi headeren If-Match som siterer ETag headeren som ble returnert av serveren:

Ved oppdateringer SKAL Serveren kreve at klienten angir headeren If-Match, dersom headeren mangler SKAL serveren returnere HTTP statuskoden 412 Pre-condition failed.

For mer informasjon, se Managing Resource Contention.

Responshåndtering

Både ved bruk av REST og FHIR med REST er det viktig at svar fra en tjener følger standardisering av HTTP status koder, for anbefalinger vedrørende responshåndtering ved tilgangsnekt se .

HTTP standarden definerer følgende status kodeserier:

• 1xx-serien er reservert for lavnivå HTTP-ting.

• 2xx-serien er reservert for vellykkede kall der alt går som planlagt.

• 3xx-serien er reservert for omadressering av trafikk.

• 4xx-serien er reservert for å svare på feil gjort av klienten, f.eks. feil inputdata eller at de ber om ting som ikke eksisterer. Disse forespørslene skal være idempotente, og skal ikke endre tjenerens tilstand.

• 5xx-serien er reservert for svar når tjeneren gjør en feil. Ofte blir disse feilene returnert av applikasjonene og normalt utenfor utviklerens rekkevidde. Dette er for å sikre at klientene faktisk mottar et svar. Klienten kan ikke muligens vite tilstanden til serveren når et 5xx-svar mottas, og derfor bør disse unngås.