Za poslední dva roky jsme navrhli přes tucet REST API pro různé klienty. Některá se povedla, některá méně. Tady je souhrn toho, co funguje, co nefunguje a co bychom udělali jinak.
URL design — konzistence nad elegancí¶
Podstatná jména, ne slovesa. /api/v1/users, ne /api/v1/getUsers. Množné číslo konzistentně. Nesting jen jednu úroveň — /users/123/orders je OK, hlubší ne. Raději /order-items/789 s filtrováním.
Verzování — URL path vyhrál¶
Zkoušeli jsme tři přístupy: URL path (/api/v1/), header (Accept: application/vnd.myapp.v1+json), query param. Vyhrál URL path — pochopí ho každý vývojář, funguje v prohlížeči a cache mu rozumí.
Error handling — buďte upovídaní¶
Naše první API vracelo: {“error”: “Bad request”}. K ničemu. Dnešní formát (inspirovaný RFC 7807):
{
"status": 422,
"code": "VALIDATION_ERROR",
"message": "Validace selhala",
"details": [
{"field": "email", "message": "Neplatný formát e-mailové adresy"}
],
"traceId": "abc-123-def"
}
HATEOAS — teorie vs. praxe¶
Zkoušeli jsme Spring HATEOAS. Pro veřejné API má smysl. Pro interní API, kde frontend tým sedí vedle? Overhead bez přínosu. Frontendáři linky ignorovali a hardcoded URL stejně. Teorie krásná, praxe jiná.
Dokumentace — Swagger je nutnost¶
Swagger generuje interaktivní dokumentaci z anotací. Game changer pro onboarding. Ale contract-first je lepší — napsat YAML ručně a generovat kód z něj. Víc práce, ale single source of truth.
Bezpečnost — OAuth 2.0 a JWT¶
OAuth 2.0 s JWT tokeny. Access token v Authorization headeru, refresh token v httpOnly cookie. JWT je self-contained — ověření nevyžaduje call na auth server. Ale JWT nelze revokovat — řešíme blacklistem v Redis.
Top 5 chyb, které jsme udělali¶
- Vraceli jsme 200 OK pro chyby (s error v body)
- Neměli jsme rate limiting — DoS od vlastního frontendu
- PUT místo PATCH pro partial update
- Žádné request/response logování
- Přílišný optimismus ohledně backward compatibility
API je produkt¶
REST API není jen technický detail — je to rozhraní pro lidi (vývojáře). Navrhujte ho s empatií. Dokumentujte ho. Verzujte ho. A hlavně — testujte ho z pohledu konzumenta.