Jak správně předávat data v REST API?

23. 5. 2025

Při návrhu endpointů v REST API často vyvstává otázka, jakým způsobem předávat data. Použít query parametry, data v těle požadavku nebo informace přímo v cestě? V tomto článku si rozebereme jednotlivé přístupy a ukážeme si, kdy je vhodné je použít.

Přehled HTTP metod

  • GET – Získání dat. Nemění stav serveru a neposílá žádný payload.
  • POST – Vytvoření nové entity. Každé volání zpravidla vytváří novou položku.
  • PUT – Aktualizace celé entity. Přepisuje ji kompletně.
  • PATCH – Částečná úprava entity. Například změna jednoho pole.
  • DELETE – Odstranění entity.

Způsoby předávání dat

Path

Parametry v cestě URL slouží k jednoznačné identifikaci konkrétní entity, nad kterou provádíme operaci.

GET /api/user/456/detail 
DELETE /api/user/456

Použitelné s metodami: GET, POST, PUT, DELETE
Používej pro: přesné určení objektu nebo jeho části (např. /user/456 nebo /product/123/image/2)

Query

Query parametry se hodí zejména pro stránkování, filtrování nebo řazení výsledků. Nejsou určeny pro přenos dat, ale pro řízení výstupu. Výhodou je, že URL s těmito parametry lze snadno sdílet.

GET /api/user/list?page=2&per-page=20&state=new

Použitelné s metodami: GET, POST, PUT, DELETE
Používej pro: filtrování, stránkování, řazení

Payload

Data odesílaná v těle požadavku, nejčastěji ve formátu JSON. Používáme je, pokud posíláme větší množství dat – například formuláře, nové objekty nebo úpravy existujících entit.

POST /api/user
{
  "name": "Jan Novák",
  "email": "jan@example.com"
}

Použitelné s metodami: POST, PUT, PATCH
Používej pro: přenos komplexních dat, tvorbu nebo úpravu objektů

Shrnutí

  • Používej path parametry pro jednoznačné určení entity
  • Query parametry pro filtrování a řazení bez změny dat
  • Payload (body) pro odesílání většího množství dat nebo formulářů

Dobrý návrh API není jen o funkčnosti – je i o čitelnosti, srozumitelnosti a konzistenci. Ulehčí práci jak tobě, tak vývojářům, kteří API budou používat.

Nejnovější příspěvky