REST

Med REST-APIet er det mulig å bruke tjenestene i Altinn i en app eller ekstern nettside.

For å komme i gang med å bruke REST API-et må du først registrere løsningen din hos Altinn og autentisere deg via ID-porten, brukernavn/passord eller virksomhetssertifikat.

Kom i gang med REST API

Selvdokumenterende hjelpeside og testklient

Altinns REST API har egne selvdokumenterene hjelpesider som inneholder detaljert teknisk informasjon om de ulike modellene som eksponeres og aksjonene som er mulig å utføre. Hjelpesidene inneholder også en testklient som kan benyttes til å utføre spørringer direkte mot Altinn API fra din nettleser (krever at du er pålogget Altinn).

Teknisk dokumentasjon og testklient

REST API - generell oppbygging

Altinn API benytter REST arkitekturstil, og baserer seg på en semantisk definisjon av innholdet. Strukturen i responsen fra API-et kan endre seg, men betydningen av elementene er den samme. Dette blir som når man navigerer seg inn på en vanlig nettside. Da kan en klient navigere seg inn i API-et ved å følge lenker med en definert betydning. Det er ikke sikkert at URL-en man var på sist fortsatt eksisterer, men det vil være mulig å bla eller søke seg tilbake til det samme innholdet fra forsiden. Fordelen med dette er at Altinn har mulighet til å bygge ut og omstrukturere innholdet i API-et uten at dette hindrer en klient fra å finne fremtil innholdet den brukte fra før.

API-et baserer seg på de mekanismene som allerede finnes i HTTP-standarden og meldingshoder som brukes av vanlige nettlesere og webservere i dag. Altinn API støtter følgende formater

• application/HAL+json
• application/HAL+xml
• application/xml
• application/json

Respons formater

Alle kall som brukes for å hente ut informasjon fra Altinn API bruker GET-metoden i HTTP. Formatet som returneres bestemmes av HTTP-headeren Accept.

Følgende kall returnerer innhold fra brukerens meldingsboks i JSON-format.

GET https://www.altinn.no/api/my/messages HTTP/1.1
Host: www.altinn.no
Accept: application/hal+json
ApiKey: myKey

Mens følgende kall returnerer innhold på XML-format:

GET https://www.altinn.no/api/my/messages HTTP/1.1
Host: www.altinn.no
Accept: application/hal+xml
ApiKey: myKey

Feilsøking

Cross-Origin Resource Sharing (CORS)

For å kunne gjøre kall mot API’et fra en webapp i et annet domene enn altinn.no, så må CORS være satt opp i Altinn.
Ønsket domene som skal benyttes spesifiseres i bestillingsskjema ved registrering av din applikasjon.

For å verifisere at CORS er satt opp korrekt i et Altinn-miljø, så kan du benytte f.eks. følgende PowerShell-script:

$headers = @{}
# Sett origin-header med domene som vil gjøre kall mot Altinn API
$headers.Add("Origin", "https://www.eksempel.no")
# Gjør test-kall i ønsket Altinn-miljø mot metadata-ressursen (som ikke krever pålogging)
Invoke-Webrequest -Method Get -Uri https://www.altinn.no/api/metadata/ -Headers $headers

Eventuelt så kan f.eks. curl benyttes:

curl -X GET -H "Origin: https://www.eksempel.no" --verbose https://www.altinn.no/api/metadata/

Hvis HTTP-header Access-Control-Allow-Origin returneres med ønsket domene, så betyr det at CORS er satt opp korrekt for det aktuelle Altinn-miljøet.

• Kom i gang med REST API

  Selv om tilgang til Altinns REST API er åpent, må du registrere din applikasjon og autentisere deg. Dette for at vi skal kunne stoppe misbruk og feilbruk.

• Autorisasjon

  APIer relatert roller, rettigheter og rolledefinisjoner. Disse endepunktene benyttes når du skal hente ut roller og rettigheter en innlogget bruker har. Du kan også slette tildelte roller.

• Innsyns­tjenester

  Oppslag i datakilder som ligger utenfor Altinn

• Meldingsboks

  Operasjoner relatert til meldinger i meldingsboks

• Metadata

  Altinn API tilbyr en ressurs som gir tilgang til metadata for tjenester tilgjengelige i Altinn. Metadata ressursen er åpent tilgjengelig og krever ikke autentisering.

• Sende/motta filer

  Operasjoner relatert til formidlingstjeneste

• Betaling

  Ved bruk av Altinns REST-api kan man videresende brukeren til betalingssteget i portal på altinn.no.

• Profil

  Altinn API tilbyr tilgang til profil-data.

• Referanse-app

  Altinn har tilgjengeliggjort referansekode for å gjøre det enklere å lage applikasjoner med Altinn-funksjonalitet.