Viktige termer

Identifikatorer

Mange dataobjekter blir identifisert med en unik identifikator (id). Denne identifikatoren kan være tekst- (kode) eller tall-basert.

Eksempler:

«KARH» er person-identifikator for innvalgt representant «Kari Henriksen» fra Vest-Agder for Arbeiderpartiet innværende stortingsperiode (2009-2013).

«1994-95» og «2010-2011» er sesjon-identifikatorer. Legg også merke til at formatet på «tilår» i identifikator er på to tegn for årstall før siste årtusen skifte og fire tegn etter siste årtusen skifte.

«47223» er sak-identifikator for sak med tittel «Finansiering og utbygging av rv 7 på strekninga Sokna - Ørgenvika i Buskerud fylke».

Det er viktig å forstå at identifikatorene er garantert unike bare innenfor sin kontekst. Det kan godt være at en fagkomité har samme identifikator som en person.

De ulike identifikatorene blir tilgjengelig for eksempel ved at man henter ut lister med personer, saker, partier, etc.

Eksportformater

Både XML og JSON (JavaScript Object Notation) er formater som støttes av datatjenesten. Dette dokumentet bruker primært xml-formatet som utgangspunkt for beskrivelser.

Alle forespørsler etter data vil kunne ha med en parameter som indikerer ønsket format på formen «format=X», der X kan være «XML» eller «JSON». Dersom formatparameter mangler, returneres data på xml-format.

For eksport på JSON format er det nå mulig å bruke JSONP. En ekstra parameter på forespørselen må indikere ønsket funksjonsnavn på formen «callback=funksjonsnavn», og da blir JSON data pakket inn på denne måten: «funksjonsnavn=(jsondata);».

Ved forespørsel etter bilde, returneres dette på jpeg format uansett formatparameter

Versjonshåndtering

Alle data objekter vil inneholde et element som gir versjonsinformasjon. For xml får det formen: «<versjon>X.Y</versjon>», der ‘X’ er nummer for hovedversjon og ‘Y’ er et nummer som angir en inkrementell utvidelse av hovedversjon. Dette betyr at for eksempel forskjellen mellom versjon 1.2 og versjon 1.3 bare vil være en utvidelse i form av ekstra elementer, alle elementer som var med i versjon 1.2 vil være med og ha samme betydning i versjon 1.3.

Kode som er skrevet for å håndtere data objekter med versjon 1.2 vil kunne håndtere data objekter med versjon 1.3.

Alle forespørsler etter data vil kunne ha med en parameter som indikerer ønsket hovedversjon på formen «versjon=X». Dersom det etterspurte data objektet finnes for den ønskede hovedversjonen vil det bli returnert med den høyeste definerte inkrementelle utvidelsen for denne hovedversjonen. Det vil si at dersom det forespørres «versjon=2», vil data objekter med «versjon2.4» bli returnert. Dersom forespørselen ikke inneholder en versjonsparameter, vil siste versjon blir returnert.

For å holde oppmerksomheten på informasjonsinnholdet i dette dokumentet er versjonsinformasjons elementer ikke tatt med i eksemplene her.

Feilhåndtering

Alle forespørsler returnerer HTTP heltalls status-koder. Normalverdien er 200 (OK).

Dersom det oppstår en feil på serversiden som ikke er grunnet forespørselen inklusive parametere, returneres statuskode 500 (Internal Server Error).

Dersom forespørselen er ukjent eller har ukjente eller ugyldige parametere, returneres statuskode 400 (Bad Request).

Vær oppmerksom på at det ikke alltid er mulig å skille mellom situasjoner der en forespørsel har en ugyldig parameterverdi og situasjoner der forespørselen normalt kan returnere et tomt resultatsett. Dette er delvis grunnet ønske om lav belastning mot databasen og teknisk implementasjon av grensesnittet mot databasen. Dette betyr at det vanligvis ikke returneres statuskode 404 (Not Found) fra denne datatjenesten.

Brukere av datatjenesten bør ikke gjøre forespørsler med «tilfeldige» identifikatorverdier, men heller sørge for å hente en liste som inneholder gyldige identifikatorer, for eksempel hente en liste med saker fra 2010-2011-sesjon, for så å bruke sakid for å hente liste med voteringer for hver eksisterende sak som har status lik «behandlet».

Dato og tid

Dato og tid bruker standard xml-format.

Eksempel:  «2009-04-12T07:20:23» bruker år-måned-dag, ‘T’ som separator mellom dato og tid, og time:minutt:sekund for tidsdelen. Der tidsdelen inneholder informasjon på deler av et sekund kommer dette med etter ‘.’ som separator som for eksempel: «2009-04-12T07:20:23.203».

Det er brukt norsk lokaltid for det gjeldende tidspunktet.

Informasjonselementer der bare datodelen er signifikant, har med tidsinformasjon av praktiske grunner. Der datoelementet betegner sluttdato for en periode er dette forsøkt indikert ved at tidsdelen har verdien «23:59:59».

Tid og dato-elementer som ikke har definert gyldig verdi, har fått verdien «0001-01-01T00:00:00».

For JSON er det ikke etablert en universell standard for dato og tid, men datatjenesten bruker formatet «\/Date(-23508000000+0200)\/», som er definert av Microsoft. Tallet «-23508000000» er antall millisekunder før eller etter 1970-01-01, og «+0200» angir tidssone 2 timer før UTC.