Jak navrhnout RESTful API s osvědčenými postupy – průvodce

Design RESTful API: osvědčené postupy pro dlouhodobou kvalitu

V dnešní digitální ekosystému je API často hlavním rozhraním vašeho produktu, přesto mnoho vývojových týmů přistupuje k jeho návrhu jako k něčemu vedlejšímu, což vede k křehkým integracím a nákladnému refaktoringu. Rozdíl mezi dobře navrženým API a špatně navrženým není jen estetický; přímo ovlivňuje produktivitu vývojářů, udržovatelnost systému a dlouhodobou životaschopnost samotné služby. Použitím osvědčených principů a vizionářského přístupu můžete vytvořit rozhraní, které nejen splňuje dnešní potřeby, ale také elegantně reaguje na neznámé zítřejší výzvy.

Co se dozvíte

Získáte praktický, na řešení orientovaný základ pro vytváření API, která přežijí a prosperují, jak se váš systém vyvíjí. Místo memorování abstraktních pravidel pochopíte kompromisy stojící za každým designovým rozhodnutím: od pojmenování zdrojů a použití HTTP metod až po verzování a zpracování chyb. Na konci budete schopni s jistotou navrhovat RESTful API s osvědčenými postupy, které jsou zároveň standardní a přizpůsobitelné, což zajistí, že vaše služba zůstane spolehlivým základem pro budoucí vývoj.

Základní principy: fundament RESTful designu

REST (Representational State Transfer) není protokol, ale architektonický styl definovaný šesti omezujícími principy. Abychom navrhli RESTful API s osvědčenými postupy, musíme nejprve pochopit tyto principy.

1. Oddělení klienta a serveru: Toto oddělení umožňuje klientovi a serveru vyvíjet se nezávisle. Dokud je rozhraní (API) stabilní, můžete měnit základní databázi, autentizační mechanismus nebo business logiku, aniž byste narušili fungování klientských aplikací.
2. Bezestavovost (Statelessness): Každý požadavek od klienta k serveru musí obsahovat všechny informace potřebné k jeho pochopení a zpracování. Server neuchovává stav relace. Toto omezení zvyšuje spolehlivost a škálovatelnost, protože jakákoli instance serveru může zpracovat jakýkoli požadavek.
3. Kešovatelnost: Odpovědi by měly explicitně nebo implicitně určovat, zda mohou být kešovány. Správné kešování může výrazně snížit latenci a zatížení serveru. Hlavička Cache-Control je vaším hlavním nástrojem.
4. Jednotné rozhraní: To je jádro REST a zdroj jeho jednoduchosti. Zahrnuje:
   • Identifikaci zdrojů: Zdroje (např. uživatelé, objednávky nebo produkty) jsou identifikovány v požadavcích, obvykle pomocí URI.
   • Manipulaci se zdroji prostřednictvím reprezentací: Když klient vlastní reprezentaci zdroje (včetně metadat), má dostatek informací k jeho úpravě nebo smazání.
   • Soběstačné zprávy: Každá zpráva obsahuje dostatek informací k popisu toho, jak ji zpracovat (např. pomocí hlaviček Content-Type a Accept).
   • HATEOAS (Hypermedia as the Engine of Application State): Toto je často opomíjené omezení. HATEOAS znamená, že klient by se měl pohybovat po API výhradně prostřednictvím hypermediálních odkazů dynamicky poskytovaných serverem. I když dosažení „čistého“ HATEOAS může být složité, zahrnutí relevantních odkazů do vašich odpovědí (např. odkaz „next“ ve stránkovaném seznamu) výrazně zlepšuje objevitelnost.
5. Vícevrstvý systém: Architektura může sestávat z hierarchických vrstev (např. bezpečnost, kešování, load balancing). To zlepšuje celkovou složitost a bezpečnost systému, protože každá vrstva by měla znát pouze tu následující.
6. Kód na vyžádání (volitelné): Server může rozšířit funkcionalitu klienta přenosem spustitelného kódu (např. JavaScript). To se v typických RESTful API používá zřídka.

1. Návrh orientovaný na zdroje: pojmenování a struktura

Prvním a nejdůležitějším krokem při navrhování RESTful API s osvědčenými postupy je definovat podstatná jména vašeho systému – zdroje. Způsob, jakým je pojmenujete a strukturujete, udává tón celému vašemu API.

Používejte podstatná jména, ne slovesa

URI reprezentuje zdroj. Mělo by to být podstatné jméno, nikoli akce.

• ❌ Špatně: /getUser, /createOrder, /updateProduct
• ✅ Dobře: /users, /orders, /products

Používejte podstatná jména v množném čísle pro kolekce

Kolekce je sada zdrojů. Používejte množné číslo pro jednotnost.

• Kolekce: /users
• Instance: /users/{userId}
• Podkolekce: /users/{userId}/orders

Udržujte hierarchickou strukturu

Zdroje přirozeně tvoří hierarchii. Vaše struktura URI by to měla odrážet. Například objednávka patřící konkrétnímu uživateli může být vnořená.

GET /users/123/orders – Získat všechny objednávky uživatele 123. GET /users/123/orders/456 – Získat konkrétní objednávku.

⚠️ Varování: Vyhněte se hlubokému vnoření více než dvou až tří úrovní. Hluboce vnořená URI (např. /users/123/orders/456/items/789) mohou být těžkopádná a často jsou známkou toho, že byste měli zjednodušit strukturu zdrojů pomocí parametrů dotazu. Místo toho zvažte /items?orderId=456.

Google AdInline article slot

2. Správné použití HTTP metod a stavových kódů

Korektnost vašeho API do značné míry závisí na správném použití HTTP sloves a stavových kódů. To je mechanismus pro manipulaci s vašimi zdroji.

HTTP metody

• GET: Získat zdroj. Měl by být bezpečný a idempotentní.
• POST: Vytvořit nový zdroj. Používá se pro operace, které nejsou ani bezpečné, ani idempotentní. Často odpověď zahrnuje hlavičku Location odkazující na nově vytvořený zdroj.
• PUT: Vytvořit nebo nahradit zdroj na konkrétním URI. Měl by být idempotentní. Klient odesílá úplnou reprezentaci zdroje.
• PATCH: Částečně aktualizovat zdroj. I když není striktně idempotentní, měl by být navržen jako idempotentní. Používejte PATCH s konkrétním mediálním typem, např. application/merge-patch+json, abyste předešli race condition.
• DELETE: Smazat zdroj. Idempotentní: opakovaný DELETE na stejné URI by měl vrátit 404 nebo 204.

Klíčové stavové kódy

• 2xx Úspěch:
  • 200 OK – Standardní úspěch.
  • 201 Created – Zdroj vytvořen. Zahrňte hlavičku Location.
  • 204 No Content – Úspěch, ale žádný obsah k vrácení (obvykle pro DELETE).
• 3xx Přesměrování:
  • 301 Moved Permanently – Použijte, když se URI trvale změnilo.
  • 304 Not Modified – Použijte s kešováním; indikuje, že se zdroj nezměnil.
• 4xx Chyby klienta:
  • 400 Bad Request – Obecná chyba na straně klienta (např. neplatný payload).
  • 401 Unauthorized – Chybí nebo je neplatná autentizace.
  • 403 Forbidden – Autentizován, ale není autorizován.
  • 404 Not Found – Zdroj nenalezen.
  • 422 Unprocessable Entity – Požadavek je formálně správný, ale sémanticky chybný (např. validační chyby).
• 5xx Chyby serveru:
  • 500 Internal Server Error – Neočekávaná chyba serveru.
  • 503 Service Unavailable – Služba nedostupná kvůli údržbě nebo přetížení.

3. Verzování a evoluce

Jedinou konstantou ve vývoji softwaru jsou změny. Dobře navržené API by mělo mít strategii evoluce. Když navrhujete RESTful API s osvědčenými postupy, způsob, jakým zacházíte s verzováním, určí životnost a udržovatelnost vašich klientů.

Držte se zpětné kompatibility

Nejspolehlivější strategií je provádět pouze zpětně kompatibilní změny. To znamená:

• Můžete přidávat nová pole do požadavků nebo odpovědí.
• Můžete přidávat nové endpointy.
• Nikdy byste neměli odstraňovat nebo přejmenovávat pole.

Někdy jsou však kritické změny nezbytné. Zde se verzování stává povinným.

Strategie verzování

Existuje několik způsobů, jak verzovat REST API. Volba často závisí na potřebách vaší organizace a stávající infrastruktuře.

Strategie	Příklad	Výhody	Nevýhody
URI Path	/v1/users, /v2/users	Nejviditelnější, nejsnadnější na implementaci a přívětivý pro vývojáře.	Časem může vést k nafouknutí URI.
Parametr dotazu	/users?version=1	Podobný URI Path, ale méně viditelný.	Může být snadno zapomenut a méně idiomatický.
Vlastní hlavička požadavku	Api-Version: 1	Udržuje URI čistá.	Vyžaduje vlastní nástroje a je méně objevitelný.
Content negotiation	Accept: application/vnd.myapp.v1+json	RESTful a využívá standardní HTTP.	Složitý na implementaci a pochopení.

Na základě syntézy průmyslových trendů (jak je pozorováno u velkých veřejných API od Stripe, Google a GitHub) zůstává strategie URI Path nejoblíbenější a nejjednodušší pro většinu týmů. Je explicitní a okamžitě sděluje vývojáři verzi API.

Strategie zastarávání

Pokud zavádíte novou verzi a označujete starou jako zastaralou, dejte klientům jasné termíny jejího odstranění. Zahrňte do svých odpovědí HTTP hlavičky Deprecation nebo Sunset. Rozumná doba zastarávání může být 12–24 měsíců, aby vývojáři měli dostatek času na migraci.

4. Kritická role dokumentace

API je tak dobré, jak dobrá je jeho dokumentace. Pokud je vaše API dokonalé, ale dokumentace je matoucí nebo chybí, vaši uživatelé budou mít potíže a vaše API selže. Specifikace OpenAPI (dříve Swagger) je de facto standardem pro dokumentaci API.

Používejte OpenAPI

Použitím OpenAPI k definici vašeho API můžete automaticky generovat interaktivní dokumentaci (např. Swagger UI), klientské SDK v několika jazycích a dokonce i serverové stuby. Dokument OpenAPI slouží jako jediný zdroj pravdy.

Praktické tipy pro dokumentaci

• Poskytujte příklady: Pro každý endpoint poskytujte reálné příklady požadavků/odpovědí. To je cennější než mnohomluvný popis.
• Vysvětlujte chybové kódy: Uveďte všechny možné chybové kódy pro každý endpoint a co znamenají. Zahrňte strukturu problem+json (jak je definováno v RFC 7807) pro jednotné zpracování chyb.
• Zahrňte průvodce začátkem: Stručný průvodce pomůže vývojářům provést první úspěšné volání API během několika minut.

5. Bezpečnost a validace dat

Bezpečnost není dodatečný nápad; musí být integrována do návrhu od samého začátku. Když navrhujete RESTful API s osvědčenými postupy, bezpečnost je nepopiratelným pilířem.

Autentizace a autorizace

• OAuth 2.0 je průmyslový standard autorizace. Umožňuje detailní řízení přístupu.
• API klíče jsou jednodušší, ale méně detailní. Používejte je pro komunikaci server-server.
• JWT (JSON Web Tokens) jsou populární pro bezestavovou autentizaci.

Bezpečnost transportní vrstvy (TLS)

Vždy používejte HTTPS pro všechny endpointy API. Používejte TLS 1.2 nebo vyšší. To chrání vaše data při přenosu před odposlechem a útoky typu man-in-the-middle.

Validace vstupních dat

Nikdy nevěřte vstupu od klienta. Validujte všechna příchozí data na hranici, než se dostanou k vaší business logice.

• Používejte bílé listiny, ne černé: Definujte, co je přesně povoleno, místo pokusů definovat vše, co je zakázáno.
• Kontrolujte datové typy, délku a formát: Ujistěte se, že string není číslo a email je platný.
• Používejte validační knihovnu: V Javě použijte Hibernate Validator; v Pythonu – Marshmallow nebo Pydantic. V Node.js – Joi nebo Zod.

6. Výkon: kešování, stránkování a filtrování

API, které je pomalé nebo složité na dotazování, bude uživatele frustrovat. Výkon je klíčovým úkolem návrhu.

Kešování

• Kešování na straně klienta: Použijte hlavičku Cache-Control k informování klientů, jak dlouho mohou odpověď kešovat. Např. Cache-Control: max-age=3600 kešuje na jednu hodinu.
• Kešování na straně serveru: Použijte reverzní proxy cache (např. Varnish) nebo distribuovanou cache (např. Redis) k ukládání častých odpovědí.
• E-Tagy: Použijte entity tags k implementaci podmíněných požadavků. Server poskytne hlavičku ETag a klient ji použije v hlavičce If-None-Match v následujících požadavcích. Pokud se zdroj nezměnil, server vrátí 304 Not Modified, čímž šetří šířku pásma.

Stránkování a filtrování

Klienti by nikdy neměli být nuceni načítat celou datovou sadu.

• Stránkování: Použijte parametry page a size nebo offset a limit. Spolehlivější přístup je „cursorové“ stránkování (pomocí tokenu, např. next_cursor), které je efektivnější pro velké datové sady a zabraňuje duplicitám při změně dat.
• Filtrování: Použijte parametry dotazu pro filtrování. Např. GET /products?category=books&price_min=10.
  • Výkonným standardem filtrování je specifikace OData, ale pro jednodušší potřeby postačí vlastní parametry dotazu.
• Řídká pole: Umožněte klientům specifikovat, která pole potřebují, čímž zmenšíte velikost payloadu. Např. GET /users/123?fields=id,name,email.

7. Testování a zajištění kvality

Přistupujte ke svému API jako k produktu. To znamená důkladné testování.

Unit testy

Testujte svou business logiku izolovaně.

Integrační testy

Testujte, jak vaše API interaguje s databázemi, kešemi a dalšími službami.

Kontraktní testy

S růstem mikroslužeb kontraktní testování (např. pomocí Pact) zajišťuje, že poskytovatel (vaše API) a spotřebitel (frontend nebo jiná služba) mohou správně komunikovat. Ověřuje, že poskytovatel splňuje očekávání spotřebitele.

End-to-end testy (E2E)

Testujte celý tok od požadavku klienta k databázi a zpět.

Často kladené otázky

1. Mám pro své nové API použít REST nebo GraphQL?

REST je skvělá volba pro jednoduchá, na zdroje orientovaná API s jasně definovanými entitami. GraphQL je užitečný, když máte silně propojená data nebo když potřebujete podporovat širokou škálu klientů s různými datovými požadavky. Zvolte REST pro jednoduchost a kešování; zvolte GraphQL pro flexibilitu a snížení overfetchingu/underfetchingu.

2. Jak zpracovávat částečné aktualizace v REST API?

Správný způsob provedení částečné aktualizace je použití metody PATCH. Váš server by měl podporovat media typ patche, např. application/merge-patch+json (RFC 7396), který serveru říká, aby aplikoval pouze poskytnutá pole. To je efektivnější než odeslání celého zdroje pomocí PUT a zabraňuje neúmyslným přepisům.

3. Jak nejlépe zpracovávat chyby a poskytovat klientovi smysluplnou zpětnou vazbu?

Používejte odpovídající HTTP stavové kódy (4xx pro chyby klienta, 5xx pro chyby serveru). V těle odpovědi vracejte konzistentní objekt chyby (podle RFC 7807), který zahrnuje URI type, title, zprávu detail a status. Tato struktura poskytuje klientovi jak programovou, tak lidsky čitelnou informaci k řešení problému.

4. Jak často bych měl měnit číslo verze API?

Zavádějte novou verzi pouze při provádění kritických změn (např. odstranění pole, změna datového typu nebo struktury požadavku/odpovědi). Nekritické změny, jako je přidávání nových polí nebo endpointů, by měly být prováděny v rámci stávající verze, aby se předešlo množení verzí a únavě vývojářů.

5. Musí REST API splňovat HATEOAS?

I když je HATEOAS jedním ze základních omezení REST, dosažení „čistého“ HATEOAS je v praxi vzácné. Pro vysoce kvalitní API je užitečné zahrnout některé hypermediální ovládací prvky, jako je odkaz self pro každý zdroj a odkazy stránkování (next, prev). To zlepšuje objevitelnost bez složitosti plnohodnotného hypermediálního enginu.

— Editorial Team