Apier.no

Endringspolicy for offentlige API-er

Apier ligger mellom systemene dine og offentlig infrastruktur som Altinn 3, Maskinporten, Brønnøysundregistrene og Skatteetaten. Disse API-ene endrer seg — sertifikater roteres, skjemaer utvides, endepunkter fases ut. Denne siden beskriver hvordan vi håndterer det, og hvilke frister du kan planlegge etter. Vi lover bare det vi faktisk kan holde.

Sertifikat- og nøkkelrotasjon

Autentisering mot offentlige API-er (Maskinporten-nøkler, TLS-sertifikater) håndteres i sin helhet på Apiers side. Du håndterer aldri offentlige sertifikater selv, og en rotasjon hos oss eller hos etaten krever ingen endring i din integrasjon. Rotasjoner gjennomføres uten planlagt nedetid; skulle en rotasjon likevel gi driftsforstyrrelse, logges den som hendelse på statussiden.

Endringer i etatenes skjemaer

Hver offentlig integrasjon går gjennom et adapterlag som normaliserer etatens svar til Apiers eget responsformat. Additive endringer oppstrøms (nye felter, nye koder) absorberes i adapteret uten at kontrakten din endres. Tvinger en oppstrøms endring frem en endring i Apiers eget responsformat, behandles den som en brytende endring etter reglene nedenfor.

Unntak: gjennomfører en etat en inkompatibel endring med kortere frist enn vår egen varslingsfrist, videreformidler vi så mye varsel som etaten gir oss, og sier eksplisitt i varselet at fristen er satt oppstrøms. Vi lover ikke en frist vi ikke kontrollerer.

Utfasing av endepunkter

Fases et oppstrøms endepunkt ut (for eksempel i overgangen Altinn 2 → Altinn 3), migrerer vi adapteret på vår side og holder Apier-kontrakten stabil der det er mulig. Fjerner vi et av våre egne endepunkter, varsles det minst 90 dager før endepunktet slutter å svare, med en dokumentert migreringsvei i endringsloggen.

Støttevindu for API-versjoner

Additiv kontrakt: eksisterende felter i v1-responser endrer aldri betydning, type eller navn, og fjernes ikke. Nye felter kan komme til — klienten din må tåle ukjente felter.
Brytende endringer: skjer kun gjennom en ny hovedversjon (for eksempel /v2), som kjører parallelt med den forrige.
Støttevindu: forrige hovedversjon støttes i minst 6 måneder etter at etterfølgeren er allment tilgjengelig.

Varslingsfrist og kanaler

Brytende endringer i Apiers eget API varsles skriftlig minst 90 dager før de trer i kraft (med unntaket for oppstrøms-tvungne endringer beskrevet ovenfor). Alle varsler publiseres i endringsloggen og feeden — det er de to kanalene vi forplikter oss til:

Endringslogg: /docs/changelog — alle brukersynlige API- og regelverksendringer.
Abonnerbar feed: /changelog.atom (Atom/RSS).
E-post: der vi har en teknisk kontaktperson for kontoen, forsøker vi i tillegg å varsle per e-post. Dette er et beste forsøk, ikke en forpliktet kanal — endringsloggen og feeden over er der alle varsler publiseres.