API'ets formål
API’et kan brukes av eksterne aktører for å undersøke om en 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.
Request
Plassering | Navn | Type | Beskrivelse |
|---|---|---|---|
Header | Authorization: bearer {access-token} | - | - |
Body | fnr | string | Innbyggers fødselsnummer el. d-nummer (11 siffer) |
omraade | int | Lovlige verdier (kun en av verdiene):
(Disse verdiene vil registreres i Volven kodeverk, 7618) Beskrivelse: Beskrivelse av områdene - hva skal brukes når:
|
Response
Plassering | Navn | Type | Beskrivelse |
|---|---|---|---|
Body | erDigitalAktivSelv | boolean | Denne vil være satt dersom innbygger er digitalt aktiv selv. NB! Et barn < 16 år vil aldri kunne være digital aktiv selv (foreløpig, men dette vil nok komme etter hvert) |
erDigitalAktivViaAndre | boolean | Denne vil være satt dersom innbygger er digitalt aktiv via andre, dvs det finnes minst en annen person som kan representere innbyggeren. Dette kan være ved foreldrerepresentasjon (hvis barn < 16 år) eller ved fullmakt. |
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 - System til System
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
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 datadeling
Beskriv eventuelle ytterligere detaljer her.
Begrensninger
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).
Hvis det er forskjeller mellom testmiljø og produksjon, utover hvilket endepunkt som benyttes, bør det også beskrives. Feks hvis det kreves ulike sertifikater, ulik type sikkerhet, etc.
Feilmeldinger
Beskriv her hvilke feilmeldinger brukeren kan få og hva de betyr
Kode | Beskrivelse |
|---|---|
200 | Alt OK |
400 | Validering av request feiler |
401 | Autorisasjon er feil eller mangler |
403 | Tilganger mangler |
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.
Alternativt kan det ligge en beskrivelse av hvordan man kan se på sidehistorikk i Confluence for å finne dokumentasjon av tidligere versjoner. Det kan også være lenker her til denne sidehistorikken.