Cara Bina REST API: Reka Bentuk, Keselamatan dan Penempatan

Untuk membina REST API, senaraikan sumber yang diurus oleh aplikasi anda (pengguna, pesanan, tempahan), berikan setiap satu URL seperti /orders dan /orders/{id}, dan guna kaedah HTTP untuk tindakan: GET untuk baca, POST untuk cipta, PATCH untuk kemas kini, DELETE untuk buang. Pulangkan JSON dengan kod status yang bermakna, sahkan setiap input, minta pengesahan identiti dan semakan kebenaran per rekod di pelayan, dan paginasikan senarai. Kemudian dokumentkan titik akhir dan lancarkan API di belakang HTTPS.

Panduan ini meliputi keputusan reka bentuk, contoh set laluan, arahan untuk pembina aplikasi AI, dan kesilapan yang menyebabkan lubang keselamatan. Jika API masih baharu bagi anda, mulakan dengan apa itu API.

Bila anda perlukan REST API

• Frontend web anda perlu menyimpan dan memuatkan data daripada pelayan
• Aplikasi mudah alih, rakan kongsi atau alat automasi perlu akses kepada data anda
• Perkhidmatan lain menghantar acara kepada anda (webhook)
• Anda sedang membahagikan kerja antara pasukan frontend dan backend

REST ialah gaya yang paling biasa, tetapi bukan satu-satunya. REST vs GraphQL menerangkan bila satu titik akhir pertanyaan yang fleksibel lebih sesuai.

Reka bentuk dahulu: sumber dan laluan

Tulis kata nama dalam aplikasi anda dan apa yang orang lakukan dengannya. Untuk aplikasi tempahan yang ringkas:

Ini sepadan dengan cipta, baca, kemas kini dan buang; lihat apa itu CRUD. Amalan yang patut diikuti:

• Kata nama jamak, tanpa kata kerja dalam URL: /bookings, bukan /getBookings.
• Bersarang hanya satu peringkat apabila ia menjelaskan pemilikan: /bookings/{id}/notes.
• Tindakan yang bukan CRUD boleh menjadi sub-sumber: POST /bookings/{id}/cancel lebih jelas daripada PATCH yang samar.
• Penamaan yang konsisten untuk medan, seperti created_at di mana-mana sahaja.

Kod status dan ralat

Guna kod HTTP standard supaya klien tahu apa yang berlaku tanpa menghuraikan teks:

Pulangkan ralat dalam satu bentuk JSON yang konsisten, contohnya {"error": {"code": "slot_taken", "message": "Masa itu tidak lagi tersedia."}}, dan jangan sekali-kali sertakan jejak tindanan (stack trace) atau ralat pangkalan data dalam respons.

Pilihan dan pertukaran

Langkah demi langkah

1. Senaraikan sumber dan laluan seperti di atas, termasuk siapa yang boleh memanggil setiap satu.
2. Modelkan data dalam pangkalan data anda dengan medan dan hubungan yang diperlukan.
3. Bina laluan baca dahulu, kemudian cipta, kemas kini dan buang.
4. Sahkan input pada setiap tulisan dengan pustaka skema: medan wajib, jenis, panjang, nilai yang dibenarkan. Tolak medan yang tidak dikenali.
5. Tambah pengesahan identiti, kemudian kebenaran per rekod: memuatkan /bookings/42 mesti menyemak bahawa tempahan 42 milik pemanggil, bukan sekadar menyemak bahawa seseorang telah log masuk.
6. Paginasikan setiap senarai dan hadkan saiz halaman.
7. Hadkan kadar untuk log masuk dan laluan yang mahal. Lihat had kadar.
8. Konfigurasikan CORS hanya jika pelayar pada domain lain perlu memanggil API, dan senaraikan asal tersebut secara jelas. Cara membetulkan ralat CORS menerangkan ralat yang akan anda temui.
9. Tulis dokumentasi dan ujian untuk setiap laluan, termasuk kes kegagalan.
10. Lancarkan dengan rahsia dalam pembolehubah persekitaran, HTTPS, log dan semakan kesihatan.

Arahan untuk pembina AI anda

Rangka asas:

Cipta REST API untuk tempahan dengan laluan berikut: GET /api/health, GET /api/bookings (dipaginasikan, maksimum 50 setiap halaman), POST /api/bookings, GET /api/bookings/:id, PATCH /api/bookings/:id, DELETE /api/bookings/:id. Simpan data dalam pangkalan data kami. Sahkan badan permintaan dengan pustaka skema dan tolak medan yang tidak dikenali. Pulangkan ralat JSON sebagai {"error": {"code", "message"}} dengan kod status yang betul (400, 401, 403, 404, 409). Simpan rahsia dalam pembolehubah persekitaran.

Keselamatan:

Minta log masuk pada setiap laluan tempahan. Pada setiap bacaan, kemas kini dan buang, semak di pelayan bahawa tempahan itu milik pengguna semasa; pulangkan 404 jika tidak. Jangan sekali-kali terima ID pengguna atau peranan daripada badan permintaan. Hadkan POST /api/bookings kepada 20 setiap minit setiap pengguna. Log ralat di pelayan tanpa memulangkan jejak tindanan.

Dokumentasi:

Tulis penerangan OpenAPI untuk laluan ini, dan README ringkas dengan contoh permintaan dan respons bagi setiap satu.

Menguji API anda

Uji dari luar frontend, kerana penyerang akan berbuat demikian:

• Setiap laluan berfungsi dengan input yang sah dan memulangkan bentuk serta kod yang didokumentasikan
• Medan yang hilang atau tidak sah memulangkan 400 dengan mesej yang jelas
• Tiada token memulangkan 401 pada setiap laluan yang dilindungi
• Pengguna A meminta rekod pengguna B melalui ID mendapat 404 atau 403
• Senarai dipaginasikan; limit yang sangat besar dihadkan
• Cipta pendua atau bercanggah memulangkan 409, bukan 500
• Had kadar memulangkan 429
• Respons ralat tidak mengandungi jejak tindanan, SQL atau rahsia
• CORS hanya membenarkan asal yang anda maksudkan

Kesilapan lazim

• Menyemak log masuk tetapi bukan pemilikan. Lubang API yang paling biasa: mana-mana pengguna yang log masuk boleh membaca sebarang rekod dengan menukar ID.
• Mempercayai klien. Harga, peranan dan ID pengguna daripada badan permintaan boleh diubah.
• Memulangkan keseluruhan baris pangkalan data. Hash kata laluan dan medan dalaman bocor. Pilih apa yang disertakan dalam setiap respons.
• Senarai tanpa had. Satu permintaan untuk setiap rekod boleh melambatkan keseluruhan aplikasi.
• 200 OK dengan mesej ralat di dalamnya. Klien dan pemantauan tidak dapat tahu ia gagal.
• CORS ditetapkan untuk membenarkan semua pada API yang menggunakan kuki.
• Tiada semakan kesihatan atau log, jadi anda tahu tentang gangguan daripada pengguna.

Untuk semakan menyeluruh sebelum pelancaran, lihat senarai semak keselamatan untuk aplikasi yang dibina AI.

Membina REST API dalam Mythex

Anda boleh meminta Mythex untuk API sebagai sebahagian daripada aplikasi anda atau sebagai perkhidmatan tersendiri. Resipi dokumentasi REST API backend mempunyai arahan permulaan: namakan rangka kerja dan laluan anda, minta ralat JSON yang jelas, simpan rahsia dalam pembolehubah persekitaran, dan sertakan Dockerfile. Backend kontena dalam Node, Python, C#, Java dan lain-lain diterbitkan melalui Dockerfile, dan Mythex mengendalikan penempatan dari Publish (backend API). Satu projek boleh menjalankan laman web dan pelayan API secara serentak, dan anda boleh bertukar antara kedua-duanya dalam pratonton. Simpan kunci sebagai rahsia projek, dan jika API memerlukan pangkalan data, minta satu dalam sembang. Untuk kerja berjadual di sekitar API anda, lihat cara menjalankan tugas latar belakang.

Soalan lazim