API-design som håller i tio år

Snabbguide: versionering och kontrakt

Bra API:er är tråkiga: förutsägbara namn, konsekventa felformat och dokumenterade kontrakt. OpenAPI-specifikationen bör vara källan som både kod och dokumentation genereras från.

Versionera genom addition – nya fält och endpoints – i stället för brytande ändringar. När brytningen är oundviklig: ge konsumenterna lång övergångstid och verktyg för migrationen.

Felhanteringen är där flest API:er avslöjar sin ålder. Ett konsekvent felformat – gärna standarden Problem Details – med maskinläsbara felkoder, begärans-id för felsökning och mänskligt läsbara förklaringar gör skillnaden mellan en integratör som felsöker på minuter och en som öppnar supportärende. Definiera formatet dag ett; att eftermontera det i hundra endpoints gör ingen.

Tänk också på evolutionen redan i fältdesignen. Booleans blir ofta enums med tiden (“aktiv” visar sig ha tre lägen), enskilda värden blir listor, och identifierare som exponerar interna sekvenser låser fast implementationen. Strängbaserade id:n, explicita enums och objekt där skalärer frestar köper framtida flexibilitet till försumbar kostnad.

Pagineringen, idempotensnycklarna och hastighetsgränserna hör också till grundplattan. Cursor-baserad paginering överlever datatillväxt där offset kollapsar, idempotensnycklar gör omförsök säkra vid betalningar och skrivoperationer, och tydligt kommunicerade kvoter med Retry-After skiljer väluppfostrade klienter från tjänsteattacker.

Tioårs-testet är till sist enkelt: kan en utvecklare som aldrig träffat teamet integrera med enbart dokumentationen och gärna en sandbox? Om svaret är ja har ni byggt något som håller.