API-design best practices: Bygg APIer som utviklere elsker å bruke

Hva er et godt API og hvorfor er design viktig?

Et API (Application Programming Interface) er grensesnittet mellom programvarekomponenter – kontrakten som definerer hvordan de kommuniserer. Et godt designet API er intuitivt, konsistent, pålitelig og veldokumentert. Et dårlig designet API er en felle for utviklere som skal bruke det og en vedlikeholdsalbatross for de som eier det.

For norske bedrifter har API-design strategisk betydning: interne APIer påvirker produktiviteten til hele utviklingsorganisasjonen, partner-APIer avgjør hvor enkelt det er å integrere med dere, og offentlige APIer er et ansikt utad som reflekterer bedriftens tekniske kompetanse. Vipps, Altinn og Digipost er eksempler på norske APIer som er kjent for god design.

RESTful prinsipper: Ressurser, HTTP-metoder og statuskoder

REST (Representational State Transfer) er en arkitekturstil for distribuerte systemer definert av Roy Fielding i 2000. De seks kjerneprinsippene er: klient-server-separasjon, statløshet, cachebarhet, lagdelt system, uniform interface og (valgfritt) code on demand.

I praksis handler RESTful API-design om tre ting: navngi ressurser som substantiver i flertall (/users, /orders, /products), bruk HTTP-metoder korrekt (GET henter, POST oppretter, PUT/PATCH oppdaterer, DELETE sletter), og bruk korrekte HTTP-statuskoder i responser (200 OK, 201 Created, 400 Bad Request, 401 Unauthorized, 404 Not Found, 500 Internal Server Error).

• Ressurs-URLer: /users/{id}/orders (substantiver, hierarkisk)
• GET /users: Hent liste over brukere
• POST /users: Opprett ny bruker
• GET /users/{id}: Hent spesifikk bruker
• PUT /users/{id}: Erstatt bruker (hele objektet)
• PATCH /users/{id}: Delvis oppdatering av bruker
• DELETE /users/{id}: Slett bruker

API-versjonering: Hold APIet bakoverkompatibelt

API-versjonering er avgjørende for å kunne forbedre APIet ditt uten å bryte eksisterende integrasjoner. Det finnes tre hovedstrategier: URL-versjonering (/v1/users, /v2/users), header-versjonering (Accept: application/vnd.api.v2+json) og parameter-versjonering (?version=2).

URL-versjonering er det vanligste valget på grunn av sin synlighet og enkelhet. Den viktigste regelen er å opprettholde bakoverkompatibilitet innenfor en versjon: legg til felter fritt, men fjern aldri eller renavn eksisterende felter. Nye versjoner introduseres kun for breaking changes, og gamle versjoner bør støttes i minst 12 måneder etter at ny versjon er tilgjengelig.

"Det er lettere å lage et strengt API og gjøre det mer fleksibelt over tid, enn å lage et fleksibelt API og prøve å stramme det inn. Start konservativt."

Autentisering og autorisasjon: OAuth2 og JWT

Moderne API-autentisering bruker nesten alltid en kombinasjon av OAuth2 og JWT. Her er en oversikt over de viktigste konseptene:

Rate limiting og API-sikkerhet

Rate limiting begrenser antall API-forespørsler en klient kan gjøre i et gitt tidsvindu. Det beskytter mot DDoS-angrep, urimelig ressursforbruk og misbruk av APIet. Standardimplementeringen returnerer 429 Too Many Requests når grensen overskrides, med Retry-After-headeren for å indikere når klienten kan prøve igjen.

For norske APIer som håndterer persondata er sikkerhet kritisk. I tillegg til rate limiting bør API-design inkludere HTTPS everywhere, input-validering og sanering, prinsippet om minste nødvendige privilegium, auditlogging av alle operasjoner og korrekt håndtering av feilmeldinger (aldri legg sensitiv informasjon i feilresponser).

• Token bucket: Fleksibel rate limiting som tillater kortvarige toppene
• Fixed window: Enkelt, men kan tillate dobbel rate ved vindusgrenser
• Sliding window: Jevnere begrensning, mer kompleks implementering
• Distribuert rate limiting: Redis-basert for horisontalt skalerte APIer
• Headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

OpenAPI og Swagger: Dokumenter APIet ditt

OpenAPI-spesifikasjonen (tidligere kjent som Swagger) er industristandarden for å dokumentere REST APIer maskinlesbart. En OpenAPI-spesifikasjon beskriver alle endepunkter, parametere, forespørselskropper, responsskjemaer og autentiseringsmekanismer i YAML eller JSON-format.

Med en OpenAPI-spesifikasjon kan du automatisk generere Swagger UI (interaktiv dokumentasjon), klientbiblioteker i mange programmeringsspråk, testsuiter og mock-servere. For norske bedrifter som eksponerer APIer til partnere eller kunder er OpenAPI-dokumentasjon et minimum for profesjonell API-levering.

API-design i norsk næringsliv

Norge er et ledende land innen digital offentlig sektor, og dette reflekteres i API-landskapet. Altinn tilbyr et av Europas mest brukte offentlige APIer med millioner av kall daglig. Vipps eMobility eksponerer betalings-APIer som brukes av tusenvis av norske bedrifter. Norsk API-økonomi vokser raskt i takt med digitaliseringstempoet.

For norske bedrifter som ønsker å bli med i API-økonomien er det viktig å investere i API-design fra starten. Et godt designet API er et konkurransefortrinn: det tiltrekker partnere, reduserer integrasjonskostnadene og gjør bedriften mer attraktiv som teknologileverandør. Ressurser som API Design Guidelines fra Microsoft, Zalando og Stripe er gode referanser.

API-design sjekkliste for norske utviklere

Før du lanserer et API bør du gå gjennom denne sjekklisten: Er ressursnavn konsekvente substantiver i flertall? Brukes HTTP-metoder og statuskoder korrekt? Er autentisering implementert med OAuth2/JWT? Er rate limiting på plass? Er det paginering for lister (cursor-basert eller offset)? Er feilresponser konsistente med problem+json-format? Er det OpenAPI-dokumentasjon? Er versjoneringsstrategien definert?

Et API er et produkt, ikke bare en teknisk implementering. Det trenger eierskap, vedlikehold, versjoneringsplan og god dokumentasjon for å leve lenge og tjene sine brukere godt. Norske bedrifter som behandler API-design med samme seriøsitet som produktdesign høster gevinsten i form av fornøyde integrerende partnere og redusert støttebelastning.