Paano Gumawa ng REST API: Disenyo, Seguridad at Deployment

Para gumawa ng REST API, ilista ang mga resources na hahawakan ng app mo (users, orders, bookings), bigyan ang bawat isa ng URL gaya ng /orders at /orders/{id}, at gamitin ang HTTP methods para sa mga aksyon: GET para magbasa, POST para gumawa, PATCH para mag-update, at DELETE para mag-alis. Magbalik ng JSON na may malinaw na status codes, i-validate ang bawat input, humingi ng authentication at pagsusuri ng permiso bawat record sa server, at i-paginate ang mga listahan. Pagkatapos, idokumento ang mga endpoint at i-deploy ang API sa likod ng HTTPS.

Sakop ng gabay na ito ang mga desisyon sa disenyo, isang halimbawang hanay ng mga route, mga prompt para sa AI app builder, at ang mga pagkakamaling nagdudulot ng butas sa seguridad. Kung bago pa sa iyo ang mga API, magsimula sa ano ang API.

Kailan ka kailangan ng REST API

• Kailangan ng web frontend mo na mag-save at mag-load ng data mula sa server
• Kailangan ng mobile app, partner o automation tool ang access sa data mo
• May ibang serbisyong nagpapadala sa iyo ng mga event (webhooks)
• Hinahati mo ang trabaho sa pagitan ng frontend at backend team

Ang REST ang pinakakaraniwang estilo, pero hindi lang ito ang isa. Ipinapaliwanag ng REST vs GraphQL kung kailan mas angkop ang isang flexible na query endpoint.

Unang disenyo: resources at routes

Isulat ang mga pangngalan sa app mo at kung ano ang ginagawa ng mga tao sa mga ito. Para sa simpleng booking app:

Nag-mamapa ang mga ito sa create, read, update at delete; tingnan ang ano ang CRUD. Mga kombensiyong sulit sundin:

• Plural na pangngalan, walang pandiwa sa URL: /bookings, hindi /getBookings.
• Isang level lang ang nesting kapag nakakatulong ito sa pagpapakita ng ownership: /bookings/{id}/notes.
• Ang mga aksyong hindi CRUD ay puwedeng maging sub-resource: mas malinaw ang POST /bookings/{id}/cancel kaysa sa magic na PATCH.
• Pare-parehong pangalan ng mga field, gaya ng created_at sa lahat ng lugar.

Status codes at errors

Gumamit ng karaniwang HTTP codes para malaman ng mga client kung ano ang nangyari nang hindi kailangang basahin ang teksto:

Ibalik ang mga error sa iisang pare-parehong JSON format, halimbawa {"error": {"code": "slot_taken", "message": "Hindi na available ang oras na iyan."}}, at huwag kailanman isama ang stack traces o database errors sa mga response.

Mga opsyon at trade-off

Hakbang-hakbang

1. Ilista ang resources at routes gaya ng nasa itaas, kasama kung sino ang puwedeng tumawag sa bawat isa.
2. I-model ang data sa database mo, kasama ang mga field at relasyong kailangan.
3. Unahin ang read routes, saka ang create, update at delete.
4. I-validate ang input sa bawat write gamit ang schema library: kinakailangang field, uri, haba, pinapayagang values. Tanggihan ang hindi kilalang field.
5. Idagdag ang authentication, saka ang authorization bawat record: ang pag-load ng /bookings/42 ay dapat magsuri na pag-aari ng caller ang booking 42, hindi lang na may naka-log in na tao.
6. I-paginate ang bawat listahan at limitahan ang laki ng page.
7. Maglagay ng rate limit sa login at sa mga mabibigat na route. Tingnan ang rate limiting.
8. I-configure ang CORS lang kung kailangang tawagin ng browser sa ibang domain ang API, at ilista nang tahasan ang mga origin na iyon. Ipinapaliwanag ng paano ayusin ang CORS errors ang mga error na makikita mo.
9. Sumulat ng docs at tests para sa bawat route, kasama ang mga kaso ng pagkabigo.
10. I-deploy na may secrets sa environment variables, HTTPS, logs at health check.

Mga prompt para sa AI builder mo

Scaffold:

Gumawa ng REST API para sa bookings na may mga route na ito: GET /api/health, GET /api/bookings (may pagination, pinakamarami 50 bawat page), POST /api/bookings, GET /api/bookings/:id, PATCH /api/bookings/:id, DELETE /api/bookings/:id. Itago ang data sa database natin. I-validate ang request bodies gamit ang schema library at tanggihan ang mga hindi kilalang field. Ibalik ang JSON errors bilang {"error": {"code", "message"}} na may tamang status codes (400, 401, 403, 404, 409). Itago ang secrets sa environment variables.

Seguridad:

Humingi ng login sa bawat bookings route. Sa bawat read, update at delete, tiyakin sa server na pag-aari ng kasalukuyang user ang booking; magbalik ng 404 kung hindi. Huwag kailanman tanggapin ang user IDs o roles mula sa request body. Limitahan ang POST /api/bookings sa 20 bawat minuto bawat user. I-log ang mga error sa server nang hindi nagbabalik ng stack traces.

Docs:

Sumulat ng OpenAPI description ng mga route na ito, at maikling README na may halimbawang request at response para sa bawat isa.

Pagsubok sa API mo

Subukan ito mula sa labas ng frontend, dahil susubukan din ito ng mga attacker:

• Gumagana ang bawat route sa tamang input at nagbabalik ng dokumentadong hugis at code
• Ang nawawala o maling field ay nagbabalik ng 400 na may malinaw na mensahe
• Walang token, nagbabalik ng 401 sa bawat protected route
• Ang record ni user B na hiniling ni user A gamit ang ID ay nagbabalik ng 404 o 403
• Naka-paginate ang mga listahan; limitado ang malaking limit
• Ang duplicate o nagbabanggaang create ay nagbabalik ng 409, hindi 500
• Ang rate limits ay nagbabalik ng 429
• Walang stack traces, SQL o secrets sa error responses
• Pinapayagan lang ng CORS ang mga origin na gusto mo

Mga karaniwang pagkakamali

• Pagtingin sa login pero hindi sa pag-aari. Ito ang pinakakaraniwang butas sa API: kahit sinong naka-log in na user ay puwedeng magbasa ng anumang record sa pamamagitan ng pagpalit ng ID.
• Pagtitiwala sa client. Ang presyo, role at user ID mula sa request body ay puwedeng baguhin.
• Pagbabalik ng buong database rows. Lumalabas ang password hashes at internal fields. Piliin kung ano ang isasama sa bawat response.
• Mga listahang walang limitasyon. Ang isang request para sa bawat record ay puwedeng magpabagal sa buong app.
• 200 OK na may mensahe ng error sa loob. Hindi malalaman ng client at monitoring na pumalya ito.
• CORS na naka-allow sa lahat sa API na gumagamit ng cookies.
• Walang health check o logs, kaya malalaman mo ang outage mula sa mga user.

Para sa mas malawak na pagsusuri bago ilunsad, tingnan ang security checklist para sa mga app na ginawa ng AI.

Pagbuo ng REST API sa Mythex

Puwede kang humingi ng API sa Mythex bilang bahagi ng app mo o bilang sarili nitong serbisyo. May panimulang prompt ang docs recipe na REST API backend: pangalanan ang framework at mga route, humingi ng malinaw na JSON errors, itago ang secrets sa environment variables, at isama ang Dockerfile. Ang container backends sa Node, Python, C#, Java at iba pa ay ipa-publish sa pamamagitan ng Dockerfile, at ang Mythex na ang bahala sa deploy mula sa Publish (API backends). Puwedeng tumakbo nang magkatabi ang website at API server ng isang project, at puwede kang lumipat sa pagitan nila sa preview. Itago ang keys bilang project secrets, at kung kailangan ng API ng database, humingi nito sa chat. Para sa mga scheduled na gawain sa paligid ng API mo, tingnan ang paano magpatakbo ng background jobs.

Mga tanong