Ako navrhnúť REST API, ktoré prežije roky a vývojári ho pochvália

Zdroje a metódy, nie slovesá

Základ REST-u je jednoduchý: URL označuje zdroj (podstatné meno), HTTP metóda označuje akciu. Nevymýšľajte slovesá do adries — máte ich v metódach.

# DOBRE
GET    /objednavky          # zoznam
POST   /objednavky          # vytvor
GET    /objednavky/42       # detail
PATCH  /objednavky/42       # uprav
DELETE /objednavky/42       # zmaž

# ZLE
POST   /vytvorNovuObjednavku
GET    /zmazObjednavku?id=42

Používajte správne stavové kódy: 200/201 pre úspech, 400 pre zlý vstup, 401/403 pre autentifikáciu a práva, 404 pre neexistujúci zdroj, 409 pre konflikt a 500 pre chybu servera.

Verziujte hneď od začiatku

Aj to najlepšie API sa raz bude musieť zmeniť. Ak nemáte verziu, každá zmena je riziko, že rozbijete niekoho integráciu. Zaveďte verziu do adresy alebo hlavičky už pri prvom vydaní:

• /api/v1/… — jednoduché, viditeľné a ľahko sa smeruje.
• Neodstraňujte polia bez varovania. Pridávať sa dá kedykoľvek, odoberať až v novej verzii.
• Deprecovanie oznámte vopred a nechajte klientom čas na migráciu.

Konzistentné chyby

Nič nerozčúli vývojára viac než API, ktoré pri každej chybe odpovie inak. Zvoľte jeden tvar chyby a držte sa ho všade:

// 400 Bad Request
{
  "error": {
    "code": "validation_failed",
    "message": "E-mail má nesprávny formát",
    "field": "email"
  }
}

Kód chyby je pre stroj, správa pre človeka. Vďaka tomu klient vie chybu spracovať aj peknú zobraziť — bez hádania z voľného textu.

Stránkovanie, filtre a idempotencia

Čo dnes vráti desať záznamov, zajtra vráti desaťtisíc. Pripravte sa vopred:

1. Stránkujte vždy. Nikdy nevracajte celú tabuľku. Použite limit a kurzor (alebo stránku) a v odpovedi uveďte, ako získať ďalšie.
2. Filtrovanie a triedenie cez query parametre. Napr. ?status=nova&sort=-datum — čitateľné a cacheovateľné.
3. Zabezpečte idempotenciu. Opakované PUT alebo DELETE nesmie napáchať škodu; pre POST použite idempotentný kľúč, aby dvojklik nevytvoril dve objednávky.
4. Dokumentujte. Aktuálna dokumentácia (napr. OpenAPI) je súčasť API, nie nadstavba. Bez nej sa aj skvelé API používa ťažko.

Dobré API je nudné. Robí presne to, čo čakáte, rovnako ako minule — a práve preto sa naň dá spoľahnúť roky. Zásada návrhu rozhraní