Web-API'er i dybden — HTTP, REST og statuskoder

Når en frontend, en mobilapp eller et fremmed system henter eller gemmer data hos din backend, sker det over et API. På webbet bygger langt de fleste API'er på HTTP — den samme protokol, browseren bruger til at hente sider. Forstår du HTTP ordentligt, forstår du fundamentet under stort set al webkommunikation, ikke bare API'er.

§HTTP — forespørgsel og svar

HTTP er bygget op om, at en klient sender en forespørgsel, og serveren sender et svar. En forespørgsel har en metode (hvad vil jeg gøre), en sti (hvad vil jeg gøre det ved), eventuelle headers (metaoplysninger) og måske en krop med data. Svaret har en statuskode (gik det godt), headers og typisk en krop med resultatet — på et web-API ofte i JSON-format. Hver forespørgsel står som udgangspunkt alene; serveren husker ikke noget mellem dem, medmindre man bevidst bygger det med fx en session eller en token.

§Metoderne fortæller hensigten

HTTP-metoderne (også kaldet verber) fortæller, hvad man vil. At bruge dem efter deres betydning gør et API forudsigeligt. En vigtig egenskab er, om en metode er sikker (ændrer ikke data) og idempotent (samme kald gentaget giver samme tilstand) — det afgør, om det er trygt at gentage et kald, der måske ikke nåede frem.

§REST — ressourcer frem for handlinger

REST er en udbredt stil for web-API'er. Kerneideen er at tænke i ressourcer — ting, der har en adresse — frem for i handlinger. I stedet for et endepunkt som 'opretBruger' har man en ressource 'brugere', som man bruger metoderne på: hent listen, opret en ny, hent en bestemt, opdatér den, slet den. Adresserne navngives efter tingene (navneord, gerne i flertal), og metoden bestemmer handlingen. Det giver et API, der er let at gætte sig til og ensartet at bruge.

§Statuskoder — svaret i ét tal

Statuskoden i svaret fortæller kort, hvordan det gik. De er grupperet i serier, og det er grupperne, du først og fremmest skal kende: 2-serien betyder succes, 3-serien betyder omdirigering, 4-serien betyder en fejl hos klienten (du sendte noget forkert), og 5-serien betyder en fejl på serveren. At bruge den rigtige kode er en del af kontrakten — en klient skal kunne reagere korrekt uden at gætte.

• 012-serien: det lykkedes — fx oprettet eller hentet
• 023-serien: klienten skal et andet sted hen
• 034-serien: klienten gjorde noget forkert — fx ugyldigt input, ikke logget ind, ingen adgang, findes ikke
• 045-serien: serveren fejlede — det er ikke klientens skyld

§Versionering og kontrakt

Når andre bygger oven på dit API, er det en kontrakt: ændrer du den brat, knækker du deres systemer. Derfor versionerer man API'er, så en ny udgave kan komme til, mens den gamle stadig virker for dem, der ikke er klar til at skifte. Dokumentér kontrakten — hvilke adresser findes, hvilke felter forventes, hvad svares — så andre kan bruge API'et uden at læse din kildekode eller gætte.

§Sikkerhed hører med

Et API er en dør ind til dine data, ofte uden en brugerflade til at skjule noget. Derfor gælder web-sikkerheden i fuld kraft: kræv login og tjek adgang på hvert kald, valider alt input på serveren, brug kryptering under transport, og overvej at begrænse, hvor mange kald en klient må sende, så API'et ikke kan overbelastes. Et åbent, udokumenteret og uovervåget API er et oplagt mål.

“Et godt API kan bruges uden at læse koden bag — metoden, adressen og statuskoden fortæller næsten alt af sig selv.”

— Almindelig læreregel i API-design