Hva er et API? REST API forklart enkelt

01Hva er et API? Servitør-analogien

Den mest kjente måten å forklare hva et API er på, er restaurantanalogien. Du er kunden, og kjøkkenet er systemet som oppbevarer dataene. Du kan ikke gå inn på kjøkkenet selv. Du ser på menyen og gir bestillingen til servitøren. Servitøren leverer forespørselen til kjøkkenet og bringer maten til deg når den er klar. I dette scenarioet er servitøren API-et.

Menyen er også API-ets dokumentasjon: den forteller hva du kan be om, hvordan du ber om det og hva du får tilbake. Du kan ikke be om noe som ikke står på menyen, og du trenger heller ikke vite hvordan kjøkkenet fungerer.

I programvareverdenen gir denne ordningen en stor fordel. Nettbutikken trenger ikke kjenne det interne systemet til fraktselskapet. Den sier til API-et fraktselskapet tilbyr «lag en etikett for denne forsendelsen» og får svaret. Begge parter kan endre sin egen interne struktur, så lenge API-avtalen holdes.

02Hva brukes et API til?

Svaret på hva et API brukes til, ligger skjult i nesten alle digitale tjenester du bruker daglig. Å velge sted på kartet på et nettsted, betale med kort, logge inn med Google eller se værmeldingen er et API-kall i bakgrunnen.

• Kobler systemer sammen: nettstedet, markedsplassen, frakten, regnskapet og betalingssystemene fungerer i én flyt.
• Reduserer manuell dataregistrering: bestillings-, lager- og fakturainformasjon går av seg selv fra ett system til et annet.
• Mater mobilapper: appen på telefonen henter data fra API-et, ikke direkte fra databasen.
• Gjør det mulig å bruke ferdige tjenester: du trenger ikke skrive betaling, kart, SMS eller e-postinfrastruktur fra bunnen av.
• Gir sikker tilgang: eksterne parter får ikke hele databasen, bare handlingene som er tillatt.

03Hva er et REST API?

API-er kan utformes i ulike stiler. Den vanligste på nettet er REST-tilnærmingen. Det korte svaret på hva et REST API er: en API-stil som bruker HTTP-protokollen, identifiserer hver dataressurs med en adresse og utfører handlinger på disse ressursene med standardmetoder.

I REST er alt en ressurs: produkter, bestillinger, kunder. Hver ressurs har en adresse, og hvilken HTTP-metode du bruker mot adressen, avgjør hva du vil gjøre. Svarene kommer som regel i JSON-format, et tekstformat som både mennesker kan lese og programmer enkelt kan behandle.

Hva er et endepunkt?

Et endepunkt (endpoint) er adressen i API-et der en bestemt handling utføres. For eksempel er /api/urunler endepunktet for produktlisten, og /api/urunler/42 er endepunktet for produkt nummer 42. En API-dokumentasjon er i bunn og grunn en liste over disse endepunktene, hvilken metode som brukes for å kalle dem og hva de returnerer.

Statuskoder

Hvert svar kommer med en HTTP-statuskode som oppsummerer resultatet. 200 betyr vellykket, 201 post opprettet, 400 ugyldig forespørsel, 401 ikke autentisert, 403 ingen tilgang, 404 ikke funnet, 429 for mange forespørsler og 500 serverfeil. En god integrasjon håndterer hver kode for seg.

04Hvordan ser en API-forespørsel ut?

En API-forespørsel består i grunnen av fire deler: adresse, metode, headere (legitimasjon, datatype) og om nødvendig en body (dataene som sendes). Under ser du en enkel leseforespørsel til et åpent test-API og et typisk JSON-svar.

Du kan sende denne forespørselen fra terminalen med curl, fra nettleseren med JavaScript eller på serveren med Python eller Node.js. Reglene er de samme, og bare verktøyet som brukes, er forskjellig.

curl -s https://jsonplaceholder.typicode.com/posts/1 \
  -H "Accept: application/json"

{
  "userId": 1,
  "id": 1,
  "title": "...",
  "body": "..."
}

const yanit = await fetch("https://jsonplaceholder.typicode.com/posts/1");
if (!yanit.ok) throw new Error(`Hata: ${yanit.status}`);
const veri = await yanit.json();
console.log(veri.title);

05API-sikkerhet og autentisering

Bortsett fra åpne test-API-er kan du ikke få tilgang til et ekte API uten å bevise hvem du er. De vanligste metodene er API-nøkler, kortlivede tilgangstokener og autorisasjonsflyter som OAuth.

Sikkerhet handler ikke bare om autentisering. Et godt utformet API gir hver bruker bare de rettighetene som trengs, validerer innkommende data og begrenser antall forespørsler for å hindre misbruk (rate limit).

• Legg aldri API-nøkler i kode som sendes til nettleseren eller i et offentlig repositorium.
• Opprett alltid forbindelsen over HTTPS.
• Lagre nøkler i miljøvariabler og fornyer dem med jevne mellomrom.
• Be bare om de tillatelsene du trenger. Hvis leserettighet er nok, skal du ikke ta skriverettighet.
• Ikke la detaljer om interne systemer lekke ut i feilsvar.

06Eksempler på API-integrasjon

API-integrasjon er når to eller flere systemer kobles sammen slik at de utveksler data jevnlig og automatisk via API-er. I den daglige flyten til en nettbutikk finner du nesten alle disse koblingene.

Når en bestilling kommer inn, oppdateres lageret i alle kanalene produktet selges i. Dette gjøres med markedsplassintegrasjon. Når bestillingen er bekreftet, hentes etikett og sporingsnummer fra fraktselskapet. Dette trinnet hører inn under fraktintegrasjon. Fakturaen sendes automatisk til kunden med e-faktura-integrasjon.

I alle disse koblingene er ikke det vanskelige å gjøre det første kallet. Svarene på spørsmål som hva som skjer når motparten ikke svarer, hvordan du hindrer at samme bestilling behandles to ganger, og hvem som varsles ved feil, avgjør forskjellen mellom en solid integrasjon og en skjør forbindelse.

API eller webhook?

I et API spør du, og motparten svarer. I en webhook varsler derimot motparten deg av seg selv når en hendelse inntreffer. I stedet for å hele tiden spørre «er det en ny bestilling?» er det ofte mer effektivt å få en melding når bestillingen kommer. Detaljene finner du i artikkelen om hva en webhook er.

07Hvor starter man med API-utvikling?

For å lære å bruke API-er er det en god start å velge et åpent test-API og sende forespørsler med curl eller et API-testverktøy. Å lese svarene, tolke statuskodene og prøve ut feilsituasjoner får begrepene raskt til å sitte.

Vil du skrive ditt eget API, må du velge et backend-språk. For en rask og lesbar start kan du se FastAPI-eksemplet i artikkelen om hva Python er, og vil du gå videre med JavaScript, kan du se Express-eksemplet i artikkelen om hva Node.js er.

Et godt API har uansett tre felles egenskaper: tydelig og oppdatert dokumentasjon, konsekvent navngiving og forutsigbare feilsvar. Hvis en utvikler som skal bruke et API, kan lese dokumentasjonen og sende den første forespørselen på noen få minutter, er designet på rett vei.