API-ets formål

API-et gjør det mulig å hente ut informasjon om digitale helseverktøy som ligger i Verktøykatalogen samt å kunne forskrive disse verktøyene til innbygger.

API-et tilbyr tjenester for å:

• Forskrive et verktøy til innbygger fra behandlerdel av verktøyet eller fra EPJ. Dette er et alternativ til at behandler logger seg på Verktøyformidleren for å forskrive verktøy til innbygger. Når et verktøy forskrives vil innbygger få verktøyet tilsendt som en oppgave med frist. Innbygger varsles om oppgaven og blir bedt om å velge å ta i bruk verktøyet. Verktøyet vil da automatisk legges i ‘Mine verktøy’. Innbygger/pasient vil oppleve det helt likt uavhengig av om behandler har brukt Verktøyformidleren eller gjort det direkte fra verktøyet/EPJ.

• Hente ut en liste med verktøy og deres metadata med mulighet for å filtrere på fagområder, målgrupper, språk, om verktøyet krever forskrivning og om verktøyet kan brukes uten å måtte logge inn på Helsenorge.

• Hente ut en liste med verktøy og deres metadata basert på søk på verktøynavn og predefinerte søkeord.

• Hente ut alle metadata for ett enkelt verktøy

• Hente ut informasjon om hvilke behandlere som har forskrevet verktøyet til aktuell innbygger. Dette er mulig ved at Helsenorge deler informasjon om behandler som har forskrevet verktøyet med verktøyet etter innlogging og oppstart.

Fordeler med API-et

• Tjeneste for å foreskrive verktøy til innbygger gir en enklere prosess for behandler når verktøy skal forskrives direkte fra verktøyet selv eller annen ekstern løsning behandler benytter (som alternativ til å bruke Verktøyformidleren). Det gjør det mulig å sende et verktøy til pasienten direkte fra ønsket løsning f.eks behandler-delen av verktøyet eller direkte fra EPJen. Dette er mest aktuelt for helsepersonell som kun skal forskrive ett spesifikt verktøy og ikke ha fleksibiliteten til å velge ut og forskrive blant alt som ligger i verktøykatalogen.

• Tjenester for å hente ut informasjon om verktøy kan benyttes av eksterne aktører som ønsker å bruke og presentere informasjon om digitale helseverktøy på Helsenorge på i sine løsninger. På denne måten kan eksterne aktører vise utvalgt informasjon om verktøy direkte fra verktøykatalogen fremfor å duplisere og manuelt vedlikeholde informasjon i egen løsning. Informasjonen vi da alltid være oppdatert og synkronisert med siste endringer som er gjort i Verktøykatalogen automatisk.

• Tjeneste for å hente ut informasjon om behandlere som har forskrevet verktøyet til innbyggere gjør det mulig for verktøyene å følge opp bruken og lage funksjonalitet basert på relasjoner mellom innbygger og behandler. Leverandører kan bruke dette til f.eks å kontrollere påkrevde sertifiseringer og lisenser, følge med på bruk og utbredelse og få innsikt i hvilke type behandlere som benytter verktøyet. Det kan også brukes for å opprette nødvendige koblinger mellom innbyggere og pasienter i verktøyet slik at f.eks verktøy med behandlerdel kan sørge for at behandler kun ser sine egne pasienter i verktøyet.

Hvordan benytte API-et

Type API

REST

Metode og parametre til endepunktet

Forskriv verktøy til innbygger

• Beskrivelse: Forskrivning av et bestemt verktøy til innbygger. Innbygger vil varsles på Helsenorge om ny oppgave og må ta et aktivt valg om å ta i bruk verktøyet (se funksjonell beskrivelse av Digitale Verktøy). Verktøyet må være definert i Verktøykatalogen på forhånd, og verktøyets unike ID må være kjent i forskrivningsfunksjonen i Verktøyet.

• HTTP-verb: POST

• Tjeneste: verktoy

• Sikkerhetsmodell: System til system. To metoder for tilgang er tilgjengelige:

  1. HelseId sin autoriseringstjeneste for maskin-til-maskin kan benyttes:

     1. Velg Helsenorge Ekstern API i HelseId sin selvbetjeningsløsning

     2. Velg deretter scope “verktoysendtilinnbygger”

     3. Når tilgangen er godkjent av Helsenorge, kan aksesstoken hentes ut fra HelseId

  2. API-klienten kan alternativt autentisere seg mot Helsenorge Sikkerhetstjeneste.

     1. API-klienten må forhåndskonfigureres på Helsenorge med sin public key

     2. API-et skal benyttes i system-til-system kontekst: 01 - System til System

     3. Deretter kan API-klienten få utsedt et AksessToken fra Helsenorge STS.

  AksessToken som mottas fra HelseId eller Helsenorge STS skal deretter være med i Authorization header i alle HTTP-requestene. Se: 02 - Kall til Helsenorge og PVK API'er og bruk av AccessToken

Request

Respons

Verktøymetadataliste

• Beskrivelse: Verktøyliste med mulighet for filtrering av metadata. Eventuelle filtre sendes med request som queryparametre.
  Tjenesten støtter paginering, default er 10 verktøy pr. side. Maks antall verktøy pr. side er 50.

• HTTP-verb: GET

• Tjeneste: SelvstendigVerktoy

• Sikkerhetsmodell: System til system. To metoder for tilgang er tilgjengelige:

  1. HelseId sin autoriseringstjeneste for maskin-til-maskin kan benyttes:

     1. Velg Helsenorge Ekstern API i HelseId sin selvbetjeningsløsning

     2. Velg deretter scope “verktoykatalog_read”

     3. Når tilgangen er godkjent av Helsenorge, kan aksesstoken hentes ut fra HelseId

  2. API-klienten kan alternativt autentisere seg mot Helsenorge Sikkerhetstjeneste.

     1. API-klienten må forhåndskonfigureres på Helsenorge med sin public key

     2. API-et skal benyttes i system-til-system kontekst: 01 - System til System

     3. Deretter kan API-klienten få utsedt et AksessToken fra Helsenorge STS.

  AksessToken som mottas fra HelseId eller Helsenorge STS skal deretter være med i Authorization header i alle HTTP-requestene. Se: 02 - Kall til Helsenorge og PVK API'er og bruk av AccessToken

Request

Request parametre:

Respons

Respons-parametere:

Verktøymetadata

• Beskrivelse: Metadata for ett valgt verktøy angitt med en unik id (guid).

• HTTP-verb: GET

• Tjeneste: SelvstendigVerktoy

• Sikkerhetsmodell: System til system. To metoder for tilgang er tilgjengelige:

  1. HelseId sin autoriseringstjeneste for maskin-til-maskin kan benyttes:

     1. Velg Helsenorge Ekstern API i HelseId sin selvbetjeningsløsning

     2. Velg deretter scope “verktoykatalog_read”

     3. Når tilgangen er godkjent av Helsenorge, kan aksesstoken hentes ut fra HelseId

  2. API-klienten kan alternativt autentisere seg mot Helsenorge Sikkerhetstjeneste.

     1. API-klienten må forhåndskonfigureres på Helsenorge med sin public key

     2. API-et skal benyttes i system-til-system kontekst: 01 - System til System

     3. Deretter kan API-klienten få utsedt et AksessToken fra Helsenorge STS.

  AksessToken som mottas fra HelseId eller Helsenorge STS skal deretter være med i Authorization header i alle HTTP-requestene. Se: 02 - Kall til Helsenorge og PVK API'er og bruk av AccessToken

Request

Respons

Respons-parametere:

Verktøysøk

• Beskrivelse: Søk som returnerer liste med navn og id på verktøy basert på verktøynavn og definerte søkeord. Søkeresultatet returnerer opp til 50 verktøy(default), men kan overstyres med paramter 'RowCount'.

• HTTP-verb: GET

• Tjeneste: SelvstendigVerktoy

• Sikkerhetsmodell: Sikkerhetsmodell: System til system. To metoder for tilgang er tilgjengelige:

  1. HelseId sin autoriseringstjeneste for maskin-til-maskin kan benyttes:

     1. Velg Helsenorge Ekstern API i HelseId sin selvbetjeningsløsning

     2. Velg deretter scope “verktoykatalog_read”

     3. Når tilgangen er godkjent av Helsenorge, kan aksesstoken hentes ut fra HelseId

  2. API-klienten kan alternativt autentisere seg mot Helsenorge Sikkerhetstjeneste.

     1. API-klienten må forhåndskonfigureres på Helsenorge med sin public key

     2. API-et skal benyttes i system-til-system kontekst: 01 - System til System

     3. Deretter kan API-klienten få utsedt et AksessToken fra Helsenorge STS.

  AksessToken som mottas fra HelseId eller Helsenorge STS skal deretter være med i Authorization header i alle HTTP-requestene. Se: 02 - Kall til Helsenorge og PVK API'er og bruk av AccessToken

Request

Respons

Respons-parametere:

Grafisk element

• Beskrivelse: Tjeneste for å hente ett bilde/ikon med id til det grafiske elementet som innparameter.

• HTTP-verb: GET

• Tjeneste: GrafiskElement

• Sikkerhetsmodell: Sikkerhetsmodell: System til system. To metoder for tilgang er tilgjengelige:

  1. HelseId sin autoriseringstjeneste for maskin-til-maskin kan benyttes:

     1. Velg Helsenorge Ekstern API i HelseId sin selvbetjeningsløsning

     2. Velg deretter scope “verktoykatalog_read”

     3. Når tilgangen er godkjent av Helsenorge, kan aksesstoken hentes ut fra HelseId

  2. API-klienten kan alternativt autentisere seg mot Helsenorge Sikkerhetstjeneste.

     1. API-klienten må forhåndskonfigureres på Helsenorge med sin public key

     2. API-et skal benyttes i system-til-system kontekst: 01 - System til System

     3. Deretter kan API-klienten få utsedt et AksessToken fra Helsenorge STS.

  AksessToken som mottas fra HelseId eller Helsenorge STS skal deretter være med i Authorization header i alle HTTP-requestene. Se: 02 - Kall til Helsenorge og PVK API'er og bruk av AccessToken

Request

Respons

Ved suksess returneres bildefil, HTTP-status 200.

Veiledningstjeneste

• Beskrivelse: Tjeneste for å oppdatere metadata på en eksisterende veiledningstjeneste

• HTTP-verb: PUT

• Tjeneste: Veiledningstjeneste

• Sikkerhetsmodell: Sikkerhetsmodell: System til system. To metoder for tilgang er tilgjengelige:

  1. HelseId sin autoriseringstjeneste for maskin-til-maskin kan benyttes:

     1. Velg Helsenorge Ekstern API i HelseId sin selvbetjeningsløsning

     2. Velg deretter scope “verktoyadminveiledning”

     3. Når tilgangen er godkjent av Helsenorge, kan aksesstoken hentes ut fra HelseId

  2. API-klienten kan alternativt autentisere seg mot Helsenorge Sikkerhetstjeneste.

     1. API-klienten må forhåndskonfigureres på Helsenorge med sin public key

     2. API-et skal benyttes i system-til-system kontekst: 01 - System til System

     3. Deretter kan API-klienten få utsedt et AksessToken fra Helsenorge STS.

  AksessToken som mottas fra HelseId eller Helsenorge STS skal deretter være med i Authorization header i alle HTTP-requestene. Se: 02 - Kall til Helsenorge og PVK API'er og bruk av AccessToken

Request

Behandlerinformasjon

• Beskrivelse: Tjeneste for å hente informasjon om en behandler som har sendt et verktøy til innbygger

• HTTP-verb: GET

• Tjeneste: Behandler

• Sikkerhetsmodell: Innbygger OIDC

Request

Request eksempel

Request-parametere

Respons

Respons-eksempel

Respons-parametere

Feilmeldinger

Swagger

Swagger - Verktøy External API

Miljøer

Standard for hvordan URL-en til API-et vil se ut i alle miljøene: https://<BaseUrl>​/verktoy/v1​/

Oversikt over tilgjengelige miljøer finnes her: Testmiljøer og endepunkter

Terms and Conditions

Vilkår og betingelser for bruk av API-et: Vilkår og betingelser for bruk av APIer og kommunikasjonsprosesser

Begrensninger

Ved forskrivning av verktøy må den eksterne aktøren på forhånd kjenne verktøyets unike GUID i Verktøykatalogen.

Testing

Oppsett av API-klient i test-miljø avtales som en del av kundeoppkoplingen

Versjonering og endringer

Dett er første versjon av API-et.