Jak vytvořit REST API: návrh, zabezpečení a nasazení

Pro vytvoření REST API si sepište zdroje, které vaše aplikace spravuje (uživatelé, objednávky, rezervace), každému přiřaďte URL, například /orders a /orders/{id}, a pro akce použijte HTTP metody: GET pro čtení, POST pro vytvoření, PATCH pro úpravu a DELETE pro smazání. Vracejte JSON s výstižnými stavovými kódy, validujte každý vstup, vyžadujte autentizaci a na serveru kontrolujte oprávnění ke každému záznamu. Seznamy stránkujte. Poté endpointy zdokumentujte a API nasaďte za HTTPS.

Tento průvodce popisuje návrhová rozhodnutí, konkrétní sadu tras, prompty pro AI nástroj na tvorbu aplikací a chyby, které vedou k bezpečnostním dírám. Pokud jsou pro vás API nová, začněte u toho, co je API.

Kdy potřebujete REST API

• Váš webový frontend potřebuje ukládat a načítat data ze serveru
• Mobilní aplikace, partner nebo automatizační nástroj potřebuje přístup k vašim datům
• Jiné služby vám posílají události (webhooky)
• Práci dělíte mezi frontendový a backendový tým

REST je nejrozšířenější styl, ale ne jediný. REST vs GraphQL vysvětluje, kdy se lépe hodí jeden flexibilní dotazovací endpoint.

Nejdřív návrh: zdroje a trasy

Napište si podstatná jména ve vaší aplikaci a to, co s nimi lidé dělají. Pro jednoduchou aplikaci na rezervace:

Tyto trasy odpovídají operacím vytvoř, čti, uprav a smaž; viz co je CRUD. Stojí za to dodržovat tyto konvence:

• Množná podstatná jména, žádná slovesa v URL: /bookings, ne /getBookings.
• Vnořte jen na jednu úroveň, když to objasní vlastnictví: /bookings/{id}/notes.
• Akce, které nejsou CRUD, mohou být podzdroje: POST /bookings/{id}/cancel je srozumitelnější než záhadný PATCH.
• Jednotné pojmenování polí, například created_at všude.

Stavové kódy a chyby

Používejte standardní HTTP kódy, aby klient poznal, co se stalo, bez čtení textu:

Chyby vracejte v jednotném JSON tvaru, například {"error": {"code": "slot_taken", "message": "Tento termín už není k dispozici."}}, a v odpovědích nikdy neuvádějte výpisy zásobníku ani chyby databáze.

Možnosti a kompromisy

Krok za krokem

1. Vypište zdroje a trasy jak je uvedeno výše, včetně toho, kdo je smí volat.
2. Namodelujte data ve vaší databázi s poli a vztahy, které potřebujete.
3. Nejdřív vytvořte čtecí trasy, poté vytváření, úpravy a mazání.
4. Validujte vstup u každého zápisu pomocí schématové knihovny: povinná pole, typy, délky, povolené hodnoty. Odmítněte neznámá pole.
5. Přidejte autentizaci, poté autorizaci pro každý záznam: načtení /bookings/42 musí ověřit, že rezervace 42 patří volajícímu, a ne jen to, že je někdo přihlášen.
6. Stránkujte každý seznam a omezte velikost stránky.
7. Omezte počet požadavků u přihlášení a náročných tras. Viz omezení počtu požadavků.
8. Nastavte CORS, jen pokud musí prohlížeče na jiných doménách volat API, a uveďte tyto původy výslovně. Jak opravit chyby CORS vysvětluje chyby, na které narazíte.
9. Napište dokumentaci a testy pro každou trasu, včetně chybových stavů.
10. Nasaďte s tajnými údaji v proměnných prostředí, HTTPS, logy a kontrolou stavu.

Prompty pro váš AI nástroj

Kostra:

Vytvoř REST API pro rezervace s těmito trasami: GET /api/health, GET /api/bookings (stránkovaně, max 50 na stránku), POST /api/bookings, GET /api/bookings/:id, PATCH /api/bookings/:id, DELETE /api/bookings/:id. Ukládej data do naší databáze. Těla požadavků validuj pomocí schématové knihovny a odmítni neznámá pole. Chyby vracej jako JSON {"error": {"code", "message"}} se správnými stavovými kódy (400, 401, 403, 404, 409). Tajné údaje drž v proměnných prostředí.

Zabezpečení:

U každé trasy pro rezervace vyžaduj přihlášení. Při každém čtení, úpravě a smazání na serveru ověř, že rezervace patří aktuálnímu uživateli; pokud ne, vrat 404. Nikdy nepřijímej ID uživatele ani role z těla požadavku. Omez POST /api/bookings na 20 požadavků za minutu na uživatele. Chyby loguj na serveru, aniž bys vracel výpisy zásobníku.

Dokumentace:

Napiš OpenAPI popis těchto tras a krátké README s ukázkovými požadavky a odpověďmi pro každou z nich.

Testování API

Testujte zvenku, mimo frontend, protože útočníci to udělají také:

• Každá trasa funguje s platným vstupem a vrací popsaný tvar a kód
• Chybějící nebo neplatná pole vrátí 400 s jasnou zprávou
• Bez tokenu vrátí každá chráněná trasa 401
• Uživatel A, který požádá o záznam uživatele B podle ID, dostane 404 nebo 403
• Seznamy jsou stránkované; obrovský limit je omezen
• Duplicitní nebo kolidující vytvoření vrací 409, ne 500
• Překročení limitů vrací 429
• Chybové odpovědi neobsahují výpisy zásobníku, SQL ani tajné údaje
• CORS povoluje jen původy, které zamýšlíte

Časté chyby

• Kontrola přihlášení bez kontroly vlastnictví. Nejčastější díra v API: libovolný přihlášený uživatel si změnou ID přečte libovolný záznam.
• Důvěra klientovi. Ceny, role a ID uživatelů z těla požadavku lze upravit.
• Vracení celých řádků databáze. Uniknou hashe hesel a interní pole. Vyberte, co každá odpověď obsahuje.
• Neomezené seznamy. Jeden požadavek na všechny záznamy může zpomalit celou aplikaci.
• 200 OK s chybou uvnitř. Klienti ani monitoring nepoznají, že selhalo.
• CORS nastavený tak, aby povoloval vše u API, které používá cookies.
• Žádná kontrola stavu ani logy, takže o výpadcích se dozvíte od uživatelů.

Pro širší kontrolu před spuštěním viz bezpečnostní kontrolní seznam pro aplikace postavené pomocí AI.

Vytvoření REST API v Mythexu

V Mythexu můžete požádat o API jako součást aplikace nebo jako samostatnou službu. Recept v dokumentaci REST API backend obsahuje startovací prompt: uveďte framework a trasy, požádejte o srozumitelné JSON chyby, držte tajné údaje v proměnných prostředí a přidejte Dockerfile. Kontejnerové backendy v Node, Pythonu, C#, Javě a dalších se publikují přes Dockerfile a nasazení z Publish zajišťuje Mythex (API backendy). Projekt může provozovat web i API server vedle sebe a v náhledu mezi nimi přepínat. Klíče ukládejte jako tajné údaje projektu a pokud API potřebuje databázi, požádejte o ni v chatu. Pro naplánovanou práci kolem API viz jak spouštět úlohy na pozadí.

Otázky