Ako vytvoriť REST API: návrh, zabezpečenie a nasadenie

Na vytvorenie REST API si najprv zapíšte zdroje, ktoré vaša aplikácia spravuje (používatelia, objednávky, rezervácie), každému dajte URL, napríklad /orders a /orders/{id}, a na akcie použite HTTP metódy: GET na čítanie, POST na vytvorenie, PATCH na úpravu, DELETE na odstránenie. Vracajte JSON s výstižnými stavovými kódmi, overte každý vstup, na serveri vyžadujte autentifikáciu a kontrolu oprávnení pre každý záznam a zoznamy stránkujte. Potom API zdokumentujte a nasaďte za HTTPS.

Tento sprievodca pokrýva rozhodnutia pri návrhu, sadu trás ako príklad, prompty pre AI nástroj na tvorbu aplikácií a chyby, ktoré spôsobujú bezpečnostné diery. Ak sú pre vás API nové, začnite s čím je API.

Kedy potrebujete REST API

• Váš webový frontend potrebuje ukladať a načítavať dáta zo servera
• Mobilná aplikácia, partner alebo automatizačný nástroj potrebuje prístup k vašim dátam
• Iné služby vám posielajú udalosti (webhooky)
• Rozdeľujete prácu medzi tím frontendu a backendu

REST je najbežnejší štýl, ale nie jediný. REST vs GraphQL vysvetľuje, kedy sa lepšie hodí jeden flexibilný dotazovací endpoint.

Najprv návrh: zdroje a trasy

Zapíšte si podstatné mená vo vašej aplikácii a to, čo s nimi ľudia robia. Pre jednoduchú aplikáciu na rezervácie:

Tieto trasy zodpovedajú operáciám create, read, update a delete; pozrite si čo je CRUD. Stojí za to dodržiavať tieto konvencie:

• Množné podstatné mená, žiadne slovesá v URL: /bookings, nie /getBookings.
• Vnorenie len o jednu úroveň, keď to objasňuje vlastníctvo: /bookings/{id}/notes.
• Akcie, ktoré nie sú CRUD, môžu byť podzdroje: POST /bookings/{id}/cancel je jasnejšie než záhadné PATCH.
• Konzistentné názvy polí, napríklad created_at všade.

Stavové kódy a chyby

Používajte štandardné HTTP kódy, aby klienti vedeli, čo sa stalo, bez parsovania textu:

Chyby vracajte v jednotnom JSON tvare, napríklad {"error": {"code": "slot_taken", "message": "Ten čas už nie je dostupný."}}, a v odpovediach nikdy neposielajte stack trace ani chyby databázy.

Možnosti a kompromisy

Krok za krokom

1. Zoznam zdrojov a trás ako vyššie, vrátane toho, kto ich smie volať.
2. Namodelujte dáta vo vašej databáze s poľami a vzťahmi, ktoré potrebujete.
3. Najprv vytvorte čítacie trasy, potom vytváranie, úpravu a mazanie.
4. Overte vstup pri každom zápise pomocou schémovej knižnice: povinné polia, typy, dĺžky, povolené hodnoty. Odmietnite neznáme polia.
5. Pridajte autentifikáciu, potom autorizáciu pre každý záznam: načítanie /bookings/42 musí overiť, že rezervácia 42 patrí volajúcemu, nielen to, že je niekto prihlásený.
6. Stránkujte každý zoznam a obmedzte veľkosť stránky.
7. Obmedzte počet požiadaviek pri prihlasovaní a náročných trasách. Pozrite obmedzenie počtu požiadaviek.
8. Nastavte CORS, len ak musia prehliadače na iných doménach volať API, a tieto pôvody vypíšte výslovne. Ako opraviť CORS chyby vysvetľuje chyby, ktoré uvidíte.
9. Napíšte dokumentáciu a testy pre každú trasu vrátane zlyhávajúcich prípadov.
10. Nasaďte s tajomstvami v premenných prostredia, HTTPS, logmi a kontrolou stavu.

Prompty pre váš AI nástroj

Kostra:

Vytvor REST API pre rezervácie s týmito trasami: GET /api/health, GET /api/bookings (stránkovane, max. 50 na stránku), POST /api/bookings, GET /api/bookings/:id, PATCH /api/bookings/:id, DELETE /api/bookings/:id. Ukladaj dáta do našej databázy. Telá požiadaviek over pomocou schémovej knižnice a odmietni neznáme polia. Chyby vracaj ako JSON {"error": {"code", "message"}} so správnymi stavovými kódmi (400, 401, 403, 404, 409). Tajomstvá drž v premenných prostredia.

Zabezpečenie:

Vyžaduj prihlásenie na každej trase rezervácií. Pri každom čítaní, úprave a mazaní over na serveri, že rezervácia patrí aktuálnemu používateľovi; ak nepatrí, vráť 404. Nikdy neprijímaj ID používateľov ani roly z tela požiadavky. Obmedz POST /api/bookings na 20 za minútu na používateľa. Chyby zapisuj na serveri do logu bez vrátenia stack trace.

Dokumentácia:

Napíš OpenAPI popis týchto trás a krátke README s príkladmi požiadaviek a odpovedí pre každú z nich.

Testovanie vášho API

Testujte zvonku, mimo frontendu, lebo útočníci to tiež urobia:

• Každá trasa funguje s platným vstupom a vracia dokumentovaný tvar a kód
• Chýbajúce alebo neplatné polia vrátia 400 s jasnou správou
• Bez tokenu vráti 401 každá chránená trasa
• Používateľ A, ktorý požiada o záznam používateľa B podľa ID, dostane 404 alebo 403
• Zoznamy sú stránkované; veľký limit je obmedzený
• Duplicitné alebo konfliktné vytvorenia vrátia 409, nie 500
• Limity požiadaviek vracajú 429
• Chybové odpovede neobsahujú stack trace, SQL ani tajomstvá
• CORS povoľuje len pôvody, ktoré ste zamýšľali

Časté chyby

• Kontrola prihlásenia bez kontroly vlastníctva. Najčastejšia diera v API: ľubovoľný prihlásený používateľ môže čítať ľubovoľný záznam zmenou ID.
• Dôverovanie klientovi. Ceny, roly a ID používateľov z tela požiadavky sa dajú upraviť.
• Vracanie celých riadkov databázy. Hashe hesiel a interné polia unikajú. Vyberte, čo každá odpoveď obsahuje.
• Neohraničené zoznamy. Jedna požiadavka na všetky záznamy môže spomaliť celú aplikáciu.
• 200 OK s chybovou správou vo vnútri. Klienti a monitoring nevidia, že zlyhalo.
• CORS nastavený tak, aby povoľoval všetko pri API, ktoré používa cookies.
• Žiadna kontrola stavu ani logy, takže sa o výpadkoch dozviete od používateľov.

Na širší kontrolu pred spustením pozrite bezpečnostný kontrolný zoznam pre aplikácie vytvorené s AI.

Budovanie REST API v Mythex

V Mythex môžete REST API vyžiadať ako súčasť aplikácie alebo ako samostatnú službu. Recept REST API backend v dokumentácii obsahuje štartovací prompt: pomenujte framework a trasy, požiadajte o jasné JSON chyby, tajomstvá držte v premenných prostredia a pridajte Dockerfile. Kontajnerové backendy v Node, Pythone, C#, Jave a ďalších sa publikujú cez Dockerfile a Mythex zvládne nasadenie z Publish (API backendy). Projekt môže bežať ako webová stránka a API server vedľa seba a medzi nimi môžete v náhľade prepínať. Kľúče ukladajte ako tajomstvá projektu a ak API potrebuje databázu, požiadajte o ňu v chate. Pre plánovanú prácu okolo vášho API pozrite ako spúšťať úlohy na pozadí.

Otázky