API-design og beste praksis — norsk guide for utviklere

Hva er et API, og hvorfor er design viktig?

Et API (Application Programming Interface) er en avtale mellom to programmer om hvordan de kommuniserer. REST API-er bruker HTTP-protokollen og er i dag den dominerende standarden for kommunikasjon mellom tjenester på internett. Enhver gang du ber om vær i en app, betaler med Vipps, eller ser venners oppdateringer på sosiale medier, snakker en app med et API bak kulissene.

Godt API-design er avgjørende av to grunner: konsistens og evolverbarhet. Et godt designet API er intuitivt — en ny utvikler kan bruke det uten å lese lange manualer fordi det oppfører seg som forventet. Et godt designet API kan vokse og endres uten å bryte eksisterende integrasjoner — dette er verdifullt i et norsk næringslivsperspektiv der mange integrasjoner lever i ti år eller mer.

Ressursorientering — kjernen i REST

REST (Representational State Transfer) er ikke en standard, men en arkitekturstil definert av Roy Fielding i hans doktorgradsavhandling fra 2000. Kjerneprinsippet er ressursorientering: alt er en ressurs med en URL, og du opererer på ressurser med HTTP-metodene GET, POST, PUT, PATCH og DELETE.

En vanlig feil er å designe API-er som RPC (Remote Procedure Call) med handlinger i URL-en: /getUser, /createOrder, /deleteProduct. Korrekt REST bruker substantiver i URL-en: GET /users/{id}, POST /orders, DELETE /products/{id}. Handlingen uttrykkes gjennom HTTP-metoden, ikke URL-en.

Sentrale designprinsipper å følge

Her er de viktigste prinsippene for REST API-design som profesjonelle norske utviklere bør kjenne:

• Bruk substantiver, ikke verb i URL-er: /users ikke /getUsers, /orders/{id} ikke /fetchOrder.
• Hierarkisk ressursstruktur: /users/{userId}/orders representerer ordrer som tilhører en bruker — intuitivt og konsistent.
• Korrekte HTTP-statuskoder: 200 OK, 201 Created, 204 No Content, 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 422 Unprocessable Entity, 500 Internal Server Error.
• Konsistent navngiving: bruk enten camelCase eller snake_case — og hold deg til det. Bland aldri. Norsk industri foretrekker camelCase for JSON-felter.
• Paginering for lister: Returner aldri ubegrensede lister. Bruk cursor-basert paginering for bedre ytelse, eller offset/limit med tydelig metadata om total antall.
• Versjonering: Inkluder versjon i URL (/api/v1/users) eller Accept-header. Endre aldri kontrakt uten å bumpe versjon.
• Idempotens: PUT, DELETE og GET skal være idempotente — kaller du dem flere ganger med samme input, gir det samme resultat. POST er ikke idempotent.
• HATEOAS (valgfritt): Inkluder lenker til relaterte ressurser i responsen — maskinene kan da navigere API-et som en bruker navigerer nettsider.

Autentisering og autorisasjon

API-sikkerhet er kritisk. De to vanligste tilnærmingene er API-nøkler og OAuth 2.0 med JWT. API-nøkler er enkle å implementere og passer for server-til-server-kommunikasjon der den kallende parten er et kjent system. Send alltid API-nøkler i Authorization-headeren, aldri i URL-en (URL-er logges av servere og mellomvare).

OAuth 2.0 med JWT (JSON Web Tokens) er standarden for API-er som betjener brukere. Brukeren autentiserer seg og mottar et access token (typisk gyldig 15-60 min) og et refresh token. API-et verifiserer JWT-signaturen uten å kontakte en sentralisert database for hvert kall — dette gjør det skalerbart. For norske offentlige tjenester er Maskinporten (Digdir) den standard autentiseringsmekanismen for maskin-til-maskin-integrasjoner.

API-markedet i tall

API-er er ryggraden i moderne digital økonomi:

Dokumentasjon — det som skiller gode fra dårlige API-er

Selv det best designede API-et er ubrukelig uten god dokumentasjon. OpenAPI Specification (OAS, tidligere Swagger) er de facto standarden for REST API-dokumentasjon. Du beskriver API-et i YAML eller JSON, og verktøy som Swagger UI, Redoc og Stoplight genererer interaktiv dokumentasjon automatisk.

Gode API-dokumentasjon inkluderer: en detaljert beskrivelse av hvert endepunkt og hvert felt, eksempler på request og response for alle vanlige scenarioer, tydelig beskrivelse av feilkoder og hvordan de håndteres, autentiseringsveiledning, og en changelog der brukerne ser hva som har endret seg. For norske offentlige tjenester er det krav om API-dokumentasjon i henhold til NAIS-plattformens standarder.

Alternativer til REST — GraphQL og gRPC

REST er dominerende, men ikke alltid det beste valget. GraphQL, utviklet av Facebook i 2012 og open sourced i 2015, lar klienten spesifisere nøyaktig hvilke data den trenger — ingen over- eller under-fetching. Det er spesielt verdifullt for komplekse, datatunge grensesnitt som mobil-applikasjoner med begrenset båndbredde. Norske selskaper som Finn.no bruker GraphQL for deler av sin API-flate.

gRPC fra Google bruker Protocol Buffers (binærformat) og HTTP/2, og er ekstremt effektivt for intern mikrotjenestekommunikasjon der ytelse er kritisk. Det er imidlertid vanskeligere å debugge og krever mer oppsett enn REST. For norske startups og SMB-er er REST med OpenAPI-dokumentasjon den anbefalte standardveien.