Metodens formål

API’et Metoden kan brukes av eksterne aktører for å undersøke om en bestemt innbygger er aktiv på Helsenorge eller ikke. Basert på svaret, kan det eksterne systemet vurdere om det kan og bør kommunisere med innbyggeren via Helsenorge og/eller om det må benytte alternative kanaler. .

Fordeler med API'et

Hvorfor bruke dette API'et fremfor noe annet. Inkluderes hvis det finnes alternative løsninger.

Hvordan benytte API'et

Type API

REST

Metoder og parametre til endepunktet

En liste over hvilke metoder som kan brukes til endepunktet, samt tabeller som sier hvilke parametre med tilhørende gyldige verdier som kan brukes pr metode. Beskriv også hva den enkelte metode generelt vil gi i respons når den brukes på endepunktet og når den brukes med ulike parametre.

POST

Beskrivelse: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Dersom formålet er å lagre innbyggers digitale status i eget system bør metoden bare benyttes etter at metoden DigitaltAktivStatusEndringer først er benyttet.

benytte API'et

Detaljert dokumentasjon av metoden

Autentisering og autorisasjon

Alle API’er krever at klienten på forhånd har autentisert seg mot vår Sikkerhetstjeneste og fått utstedt et aksesstoken som skal være med i tjenestekallene til det enkelte API. DigitalAktiv tjenesten krever ikke at kallet utføres i context av en innlogget bruker dvs. UseCase 1 (system-til-system) beskrevet her kan benyttes: 01 - System til System

Type API

REST

HTTP verb

Det skal benyttes POST og alltid https.

For å unngå at innbyggers fødselsnummer er en del av parameterne i URL’en, og dermed vil vises i browser-historikk, benyttes alltid POST med parametere i requestens body.

Request

Response

Swagger

https://eksternapi-hn-mas-02.int-hn.nhn.no/digitaltaktiv/swagger/index.html

Autorisering

Alle API’er krever at klienten på forhånd har autentisert seg mot vår Sikkerhetstjeneste og fått utstedt et aksesstoken som skal være med i tjenestekallene til det enkelte API. DigitalAktiv tjenesten krever ikke at kallet utføres i context av en innlogget bruker dvs. UseCase 1 (system-til-system) beskrevet her kan benyttes: 01 - Sikkerhetsmodell og Helsenorge STS

Autentisering

Bør inkluderes hvis brukeren må autentisere seg. Her må det stå hvordan man feks får tak i en nøkkel og hvordan den formidles ved kall til API'et. Lag gjerne en lenke til dokumentasjon om relevant metode, feks Basic Authentication eller OAuth2.

Bør også inkludere et eksempel på hvordan dette vil se ut.

curl -XGET -u my_api_key: https://api.companieshouse.gov.uk/company/00000006

Miljøer

Standard for hvordan URL’en til API’et vil se ut i alle miljøene: https://<miljø>/DigitaltAktiv/api/<versjon>/DigitaltAktivOmraade

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

Terms and Conditions

Vilkår og betingelser for bruk av API'et. Generell oversikt over alle vilkår finnes her: Vilkår og betingelser som regulerer datadelingfor bruk av APIer

Beskriv eventuelle ytterligere detaljer her.

Hvis API'et har begrensninger, feks på antall kall totalt, pr sekund, etc, så bør dette beskrives her.

Beskriv også hva som evt skjer når begrensningene nås, feks om brukeren vil få en feilmelding når den har nådd kvoten sin, samt hva brukeren da kan gjøre for å løse problemet.

Quick Start

Eksempel på hvordan raskt komme i gang med bruk av API'et, feks med Postman eller lignende. Inkluder også eksempel på en enkel request og response:

Request

Response

Testing

Beskriv hvordan brukeren kan teste at de kan benytte endepunktet, samt hvilket av miljøene som skal benyttes til dette formålet.

Beskriv gjerne også vanlige problemer brukeren kan oppleve, med evt referanse til aktuelt kapittel (slik som autorisering og autentisering).

Quick Start

Request (eks.)

Header:

Image Added

Body:

{
  "fnr": "07118600295",
  "omraade": 1
}

Response (eks.)

Body:

{
    "erDigitaltAktivSelv": true,
    "erDigitaltAktivViaAndre": true
}

Feilmeldinger

Beskriv her hvilke feilmeldinger brukeren kan få og hva de betyr

Ved HTTP-statuskoder som tilsier at det har oppstått en feil returneres også en respons med feilkode og feilmelding.

Eks:

{  "Code": "SEC-110000",  "Message": "Token is expired or invalid"}

Versjonering og endringer

Beskriv hvordan versjonering håndteres for API'et. Noen punkter som bør med:

• Har de ulike versjonene forskjellig namespace? Feks blalbalba/v1/detteeretendepunkt

• Hvor mange versjoner vil vedlikeholdes samtidig?

• Hvor lenge vedlikeholdes gamle versjoner av API'et?

• Hvordan varsles brukerne om endringer, nye versjoner og frafall av støtte til gamle versjoner?

Dokumentasjon av tidligere versjoner

Det gjeldende dokumentet er dokumentasjon av den nyeste versjonen av API'et. I dette avsnittet bør det ligge lenke til dokumentasjon av eventuelle tidligere versjoner av API'et.