API

Begrebet dækker to forskellige lag. Et biblioteks- eller styresystem-API (POSIX, Win32, et sprogs standardbibliotek) er en kontrakt på kildekodeniveau, som afgøres ved kompilering eller linkning, og det er forskelligt fra ABI'en, den binære kontrakt om kaldkonventioner og datalayout, der afgør, om kompileret kode stadig kan linkes efter en opgradering. Et netværks-API er en kontrakt over en protokol. På nettet er de dominerende stilarter ressourceorienteret REST over HTTP, RPC-stilarter som gRPC (Protocol Buffers over HTTP/2) og JSON-RPC 2.0, GraphQL med ét endpoint og felter, som klienten selv vælger, samt hændelsesdrevne grænseflader som webhooks. Kontrakterne skrives ned i maskinlæsbar form: OpenAPI-dokumenter til HTTP-API'er, .proto-filer til gRPC, GraphQL's schema definition language og AsyncAPI til hændelsesgrænseflader.

At videreudvikle et API uden at ødelægge det for forbrugerne er det centrale tekniske problem. Nye valgfrie felter er kun kompatible, hvis klienterne ignorerer ukendte felter (tolerant reader-mønsteret); at fjerne, omdøbe eller ændre typen på et felt bryder dem. Udbydere versionerer i stien (/v2), i en header eller i medietypen og varsler udfasning med Sunset-headeren (RFC 8594). Hyrums lov beskriver grænsen for alle kontrakter: med nok brugere vil nogen afhænge af enhver observerbar adfærd, også udokumenteret rækkefølge eller fejltekster. Driftssemantik hører også til kontrakten: paginering, rate limiting besvaret med 429 Too Many Requests (RFC 6585) og Retry-After samt idempotensnøgler, der gør gentagelse af ikke-idempotente POST-kald sikker.

OWASP API Security Top 10 (udgaven fra 2023) viser, hvor API'er fejler: API1 Broken Object Level Authorization, hvor serveren accepterer et objekt-id fra klienten uden at tjekke ejerskab; API3 Broken Object Property Level Authorization, som dækker mass assignment og for meget data i svarene; API5 Broken Function Level Authorization; API4 Unrestricted Resource Consumption; og API9 Improper Inventory Management, dvs. glemte gamle versioner og udokumenterede "shadow"-endpoints. Autentificering spænder fra API-nøgler, der identificerer en applikation, men sjældent en bruger, og som ofte lækker, over OAuth 2.0-bearer tokens (RFC 6750) og JWT-adgangstokens, der skal valideres for udsteder, modtager og udløb, til gensidig TLS med certifikatbundne tokens (RFC 8705).

Et API må ikke forveksles med naboerne: en protokol (HTTP) er den transport, API'et bruger, et endpoint er én adresserbar operation i det, et SDK er et klientbibliotek, der pakker det ind, og en API-gateway er infrastruktur foran det, der står for routing, autentificering og rate limiting, men ikke kan håndhæve autorisation på objektniveau, fordi det kræver forretningsviden, som kun API'et selv har.