Overordnet teknisk beskrivelse for API

Her finner du en teknisk beskrivelse av APIet og informasjon om versjonering, formater og begreper.

Teknologi

Løsingen tilbyr en RESTful API basert på ASP.NET Web API.

Swagger UI er tilgjengelig for enkel utforskning av tilgjengelig API metoder og parametere.

Datasett eksportert på API er dokumentert på tilhørende sider.

Versjonering

Hoved-versjon er en integrert del av API url.

Eksempel url: https://data.regjeringen.no/api/v1/partier&api_key=abrakadabra 

Ved modifikasjon av data eksportert på API vil bare under-versjon oppdateres dersom det er snakk om små tillegg som ikke modifiserer forståelsen av datasettene, og som ikke krever endringer i kode som bruker datasettene. Alle datasett eksportert fra API vil inneholde informasjon om gjeldende hoved-versjon og under-versjon.

Ved større endringer og eventuell fjerning av deler fra eksisterende datasett vil det bli etablert en ny hoved-versjon.

Formater

Data kan eksporteres på JSON format eller XML format.

Eksempler på eksport data er her vist på JSON format.

Dato og tid eksportert på API er lokaltid med ISO format ('YYYY-MM-dd' eller 'YYYY-MM-dd HH.mm.ss').

Unike id'er

Det er verdt å nevne prinsippet for unike id’er i datatjenesten. Alle datasett-typer har en id-parameter som har spesifikt mønster og innhold, en spesifikk del av mønsteret er at det starter med et prefiks som definerer kontekst, det vil si datasett-typen. Mange datasett-typer har en dato i sitt id mønster, i så fall definerer dato når det spesifikke datasettet ble aktivt. Andre datasett-typer kan ha et løpenummer i stedet for dato. Det finnes også datasett-typer som har bruker et annet datasett sin id som en del av sitt id mønster. Et eksempel på dette er en statsråd «STATSRAD_INM_ER_2017_10_20_REGJ_ES_2013_10_16». Dette er Ine M. Eriksen Søreide som 2017-10-20 ble Utenriksminister i Erna Solbergs regjering (dannet 2013-10-16).

I dette statsråd id-mønsteret er det også bakt in deler av en person-id. Person id for Ine M. Eriksen Søreide er «PERSON_INM_ER».

Fra dato og til dato

Et annet moment som er verdt å nevne er forståelsen av dato og tid når dette brukes for å beskrive en periode. Et typisk eksempel er et departement som reorganiseres og bytter navn og eventuelt kode. Den terminerte versjonen av departementet får da en «TilDato» som har samme verdi som den nye versjonen sin «FraDato». Forståelsen av dette skal være at «FraDato» gjelder «fra og med», og «TilDato» gjelder «frem til». Samme prinsipp gjelder også når tidspunkter tas med i periode beskrivelser.

For å redusere «støy» i eksemplene har vi også tatt bort «respons_dato_tid» og «versjon» informasjon. I produksjonsmiljøet vil dette komme med for å lette feilfinning og kommunikasjon med brukere av API. 

Alle datasett som ligger lagret i databasen har «notis» og «registrering_dato_tid» parametere.

Parameteren «notis» blir brukt for å indikere om spesielle forhold ved registreringen av datasettet.

Parameteren «registrering_dato_tid» indikerer når datasettet ble registrert/oppdatert.