Generelt om REN API

REN IT <post@ren.no>

Dette dokumentet beskriver hvordan man får tilgang til, samt tar i bruk REN Webservice API. Dokumentet blir kontinuerlig oppdatert etterhvert som API-et utvikler seg.

Introduksjon

REN APIer

Helheten REN Webservice API er delt inn i flere APIer basert på hva de berører. Her har vi f.eks. et API for sjekklister og et for RENblad og andre dokumenter. Hvert av disse APIene er frittstående, med egen versjonering og egen rot-URL. Men i utformning er de svært like, og det aller meste av dokumentasjonen gjelder felles for dem alle.

Teknologier

RENs API er i hovedsak basert på REST og JSON, og Oauth 2 brukes for autentisering. Deler av APIet berører personlige data eller selskapsdata, og krever da REN konto og brukerautentisering gjennom brukernavn og passord.

Betingelser for bruk

Les betingelser for bruk av REN API

Tilbakemeldinger

Bruk tilbakemeldingskjema nede til høyre for å komme i kontakt med oss.

Ved feil på API som må utbedres umiddelbart ring 47479900 (9-15).

Dokumentasjon

Dette dokumentet inneholder generell informasjon om alle REN APIer. Gjennom menyen oppe på toppen av siden får man tilgang til sider med informasjon spisset til hvert enkelt API.

Detaljert dokumentasjon over selve endepunktene og datastrukturene er live-generert. Denne delen av dokumentasjonen er på engelsk. For mer informasjon, se avsnitt API-dokumentasjon.

Autentisering

REN API krever OAuth 2 autentisering, enten med "client credentials grant" for brukerløs maskin-maskin kommunikasjon, eller "resource owner password credentials grant" dersom man trenger tilgang til bruker- eller selskapsdata.

Se https://oauth.net/2 for spesifikasjon av standarden.

Klient-ID

REN utsteder en Oauth2 klient-ID til selskap som vil integrere. Den er kun gyldig for det selskapet, og skal ikke deles med andre selskap. Med klient-IDen følger en hemmelig nøkkel som under ingen omstendigheter skal eksponeres. Dette betyr blant annet at direkte kall mot REN API ikke er tillatt fra en nettleser-applikasjon. Slike kall må først delegeres til en egen backend-server, som så kan utføre kallet mot REN API.

Klient-IDen kan gjenbrukes av selskapet i andre applikasjoner om de så ønsker. Dersom dette gjelder forskjellige REN APIer må klient-IDen gis tilgang til alle disse. Ta kontakt med REN for å få en klient med tilgang til det dere trenger.

Access token

Oauth 2 støtter forskjellige flyt (engelsk: flows) basert på typen applikasjon samt behov. Samtlige ender opp med en access token som skal sendes sammen med hvert kall. Denne access token har per idag en levetid på 15 minutter, og kan gjenbrukes så lenge den ikke har løpt ut. Man trenger altså ikke å hente ny access token for hvert kall.

Brukerløs autentisering

Den enkleste formen for autentisering er det som i Oauth 2 kalles "client credentials grant". Den er egnet for maskin-maskin autentisering hvor en personlig autorisasjon ikke er nødvendig.

Flyten mellom server og klient er slik at klienten sender en HTTP POST til {tokenUrl} med følgende body parametre til autorisasjonsserveren:

  • grant_type - verdi client_credentials

  • client_id - verdi {clientId}

  • client_secret - verdi {clientSecret}

  • scope - tom verdi

Autorisasjonsserveren svarer med et JSON-objekt som inneholder bl.a. følgende attributter:

  • token_type - verdi Bearer

  • expires_in - en integer som representerer TTL for access token

  • access_token - selve tokenet

For REN sitt produksjonsmiljø gjelder følgende:

Bruker-autentisering

Dersom APIet trenger tilgang til bruker- eller selskapsdata må man bruke brukerautentisering. Det betyr at sluttbrukeren selv må taste inn sitt brukernavn og passord, og disse vil bli brukt i tillegg til den klient-baserte autentiseringen. I Oauth 2 terminologi heter dette "resource owner password credentials grant".

Flyten mellom server og klient er ved at klienten sender en HTTP POST til {tokenUrl} med følgende body parametre til autorisasjonsserveren:

  • grant_type - verdi password

  • client_id - verdi {clientId}

  • client_secret - verdi {clientSecret}

  • scope - tom verdi

  • username - brukerens brukernavn eller epost

  • password - brukerens passord

Autorisasjonsserveren svarer med et JSON-objekt som inneholder bl.a. følgende attributter:

  • token_type - verdi Bearer

  • expires_in - en integer som representerer TTL for access token

  • access_token - selve tokenet

For REN sitt produksjonsmiljø gjelder følgende:

Det finnes en generell konsensus om at "resource owner password credentials grant" ikke er en anbefalt flyt i Oauth 2, siden det baserer seg på passord, som i Oauth 2 kan betegnes som en anti pattern. REN har likevel foreløpig valgt å støtte denne flyten for brukerautentisering, siden den for eksterne integratører er den enkleste og mest naturlige formen å autentisere REN-brukere på. Kritikken går ut på at klient-applikasjonen (altså integratørens applikasjon) får tilgang til all brukerens data, og kan missbruke dette uten at brukeren er involvert. Siden REN har kun et begrenset antall velkjente integratører, samt kontrollerer API-tilgangen for disse, så ser REN foreløpig ikke dette som et problem i praksis.

API-dokumentasjonen

I den generert API-dokumentasjonen finner man for hvert REST-endepunkt en seksjon Security som forteller to ting. 1) Den forteller hvilke roller som krevs. 2) Den forteller hvilke flyt som er støttet: oauth2-client og/eller oauth2-password. Dersom oauth2-client ikke er støttet så kan ikke brukerløs autentisering brukes for det endepunktet.

Eksempler

Eksempel på å hente access token via "client credentials grant", med HTTP POST og Basic Auth, mot REN produksjonsmiljø:

curl -u \{clientId}:\{clientSecret} https://www.ren.no/auth/realms/www.ren.no/protocol/openid-connect/token -d 'grant_type=client_credentials'

Eksempel på å hente access token via "client credentials grant", med HTTP POST og parameter i HTTP bodyen, mot REN produksjonsmiljø:

curl https://www.ren.no//auth/realms/www.ren.no/protocol/openid-connect/token -d 'grant_type=client_credentials&client_id=\{clientId}&client_secret=\{clientSecret}'

Ved suksess vil man få en access token tilbake i JSON format:

{"access_token":"eyJhbGciOiJSUz...O4JkOrYn1eQ","expires_in":900,"refresh_expires_in":7200,"refresh_token":"eyJhbGciOiJSUzI1Ni...z3K_Fy3buXxrbfA","token_type":"bearer","id_token":"eyJhbGciOiJSUzI1N...Wom-o3fHcJP1xccpQ","not-before-policy":1477054899,"session_state":"d2be6355-d1da-4807-8ff2-0073712b7b01"}

I eksempelet over har man fått en access token med TTL på 900 sekunder. Innenfor 900 sekunder kan man bruke samme token, før den utløper.

Bruk av REN API

Versjonering

REN versjonerer sine APIer basert på bakoverkompatibilitet. Dette betyr at den synlige versjonen, for eksempel 1.0, ikke innebærer et låst API. APIet vil kunne utvides etter hvert uten at versjonen endres - så lenge endringene er bakoverkompatible. Derfor må integratører f.eks. takle at nye egenskaper og endepunkter blir lagt til.

Når det omsider blir nødvendig med en ny versjon, så vil REN informere sine integratører, og i en overgangsfase støtte både gammel og ny versjon. Deretter vil gammel versjon slutte å virke.

For å ha kontroll på hvilken versjon som en integratør trenger, krever REN API at versjonsnummeret blir sendt inn i HTTP header "api-version". Om denne header utelates vil man som svar få:

{
    "msg" : "Missing API version header 'api-version'. Current API version is '1.0'",
    "statusCode" : 400,
    "statusText" : "Bad Request"
}

Alle svar fra REN API vil innholde samme HTTP header "api-version", men denne gangen med den siste versjonen som applikasjonen kjører på.

Hvert REN API (f.eks. APIet for sjekklister og APIet for dokumenter) har sin egen versjonering.

Opsjoner

Følgende opsjoner kan brukes, som HTTP header, ved kall til REN API:

Tabell 1. Opsjoner
Navn Verdi Betydning

api-version

API-versjonen som klientapplikasjonen er bygget mot

Se avsnitt Versjonering. Påkrevd.

pretty

true eller false

Slår på eller av "pretty printing" for JSON-svar. Default er på, hvilket er mer brukervennlig og lettlest, men ikke anbefalt for produksjon. Å slå av "pretty printing" kan spare en god del båndbredde, og vil gi bedre ytelse.

Datoer

For datoformatering brukes en variant av ISO 8601 som inkluderer millisekunder. Dette betyr følgende format:

yyyy-MM-dd’T’HH:mm:ss.SSSZ

f.eks.

2018-12-17T13:34:28+02:00

2018-12-17T13:34:28Z

Som input kan også ISO 8601 uten tid brukes:

yyyy-MM-dd

f.eks.

2018-12-17

API-dokumentasjon

Dokumentasjonen over selve endepunktene og datastrukturene er live-generert og på engelsk. Vanskelige termer er inline oversatt til norsk.

API-dokumentasjonen kan leses via REN sin API Browser. Denne kan vise dokumentasjon via Swagger UI, samt i AsciiDoctor-generert HTML-format. Den muliggjør også nedlasting av generert kode, som kan bli brukt som utgangspunkt for en integrasjon. Siden REN API støtter seg på Swagger / OpenAPI standard, så kan mange eksterne verktøy også brukes.

REN sin API Browser kan gjennom Swagger UI også brukes for å teste ut endepunktene. Man må klikke "Authorize" oppe til høyre og taste inn autentiseringsinformasjon. Deretter kan man på hvert enkelt endepunkt klikke "Try it out" og kjøre valgfrie kall mot endepunktet. Et annet alternativ er å bruke f.eks. Postman (https://www.getpostman.com).

Gå til API Browser

Endringslogg

Tabell 2. Endringslogg for dokumentet
Dato Beskrivelse

18.05.2021

API betingelser for bruk lagt til

17.12.2018

Generell informasjon om datoformatering.

18.05.2021

Første versjon.