Trasy a CRUD

Trasy jsou vstupní body vašeho API. Jsou seskupené podle zdroje a můžete je psát ručně nebo je generovat z modelu.

Definování trasy

Trasa nese metodu, cestu, parametry a odpovědi. Cesta používá syntaxi {{param}} Restormu: jakmile v cestě napíšete {{id}}, objeví se odpovídající parametr; jeho odstraněním se smaže.

Parametry

Karta Definice trasy vypisuje její parametry — parametry cesty (vytvořené z placeholderů {{param}}) a parametry dotazu / hlavičky, které přidáte pomocí Přidat parametr. Každý nese název, umístění (v), zda je povinný, popis a volitelně příklad.

Buňka Typ je kombinované pole: vyberte primitivum (string, integer, number, boolean) nebo jeden z pojmenovaných enumů návrhu jediným kliknutím. Pro bohatší případy zvolte Advanced… a otevřete malé okno, kde můžete:

• učinit z parametru pole a zvolit jeho typ prvku (array<string>, …) — vícehodnotový parametr dotazu;
• dát mu inline hodnoty enumu (povolenou množinu, vypsanou jako žetony), když není typován pojmenovaným enumem;
• Extrahovat do pojmenovaného enumu — povýšit tyto inline hodnoty na sdílený enum (viz Modely a enumy).

Parametr může být také propojen s vlastností modelu (sloupec Propojení s modelem), po níž dědí typ, nebo označen jako zastaralý. Každý parametr — jeho typ, jeho enum, jeho zastarání — se promítá do vygenerované dokumentace a do každé projekce protokolu.

Generování CRUD

Z nastavení modelu Generovat CRUD vytvoří jedním kliknutím skupinu tras pojmenovanou podle množného čísla modelu, se šesti trasami:

Trasa	Metoda a cesta	Odpovědi
Seznam	GET / (stránkováno)	200
Získat	GET /{{id}}	200 · 404
Vytvořit	POST /	201
Nahradit	PUT /{{id}}	200 · 404
Aktualizovat	PATCH /{{id}}	200 · 404
Smazat	DELETE /{{id}}	204 · 404

Seznam je stránkovaný (posun/offset, 20 prvků výchozí, 100 maximálně). Každé {{id}} je automaticky propojeno s identifikátorem modelu.

Dialogové okno Generovat CRUD nabízí dvě možnosti:

• Nahradit existující trasy — abyste se vyhnuli duplicitám, když generujete znovu.
• Chránit trasy zápisu ověřováním — vytvoření, nahrazení, aktualizace a smazání pak vyžadují token (bearer), zatímco čtení zůstávají veřejná.

Rovněž připomíná, že CRUD je servírován v každém protokolu: trasy REST, dotazy a mutace GraphQL, metody gRPC, sada entit OData a operace SOAP (viz Servírování návrhu jako mock).

Generování tras vyhledávání

Pro každou vlastnost označenou jako searchable přidá Generovat trasy vyhledávání parametr dotazu propojený s trasou seznamu modelu (a vytvoří tuto trasu, pokud ještě neexistuje).

Ověřování

Ověřování se nastavuje na třech úrovních: výchozí hodnota návrhu, vyžadované ověřování na skupinu a přepsání na trasu (které dědí výchozí nastavení skupiny). Dostupné režimy jsou Žádné, Bearer (JWT), API klíč (hlavička) a Basic.

Štítky

Štítky seskupují trasy pro dokumentaci a export OpenAPI. Existují na dvou úrovních: trasa nese své vlastní štítky (její karta Definice) a skupina nese sdílené štítky (její nastavení) uplatněné na každou trasu, kterou obsahuje. Efektivní štítky trasy jsou sjednocením obou — štítek společný celé skupině je proto nejlepší nastavit jednou na skupině. Když převedete importované API na návrh, štítek přítomný na všech trasách skupiny se automaticky vyzdvihne na skupinu.

Zastarání

Trasa (stejně jako vlastnost nebo parametr) může být označena jako zastaralá ze svých Nastavení. Zastaralá trasa se v seznamu Tras a ve vygenerovaných klientech zobrazuje ztlumeně a nese na své kartě upozornění na zastarání. Příznak se propaguje do každé projekce protokolu — deprecated v OpenAPI, direktivy @deprecated v GraphQL, deskriptorů SOAP a gRPC a metadat OData — aby jej viděli konzumenti kteréhokoli servírovaného protokolu.