Cara Membuat REST API: Desain, Keamanan dan Deployment

Untuk membuat REST API, daftarkan resource yang dikelola aplikasi Anda (pengguna, pesanan, booking), beri setiap resource URL seperti /orders dan /orders/{id}, lalu gunakan metode HTTP untuk setiap aksi: GET untuk membaca, POST untuk membuat, PATCH untuk memperbarui, dan DELETE untuk menghapus. Kembalikan respons JSON dengan status code yang tepat, validasi setiap input, wajibkan autentikasi dan pemeriksaan izin per data di server, serta gunakan pagination untuk daftar. Setelah itu, dokumentasikan endpoint dan deploy API di balik HTTPS.

Panduan ini membahas keputusan desain, contoh route, prompt untuk AI app builder, dan kesalahan yang sering menyebabkan celah keamanan. Jika API masih baru bagi Anda, mulailah dengan apa itu API.

Kapan Anda membutuhkan REST API

• Frontend web Anda perlu menyimpan dan memuat data dari server
• Aplikasi mobile, mitra, atau alat otomasi perlu mengakses data Anda
• Layanan lain mengirim event kepada Anda (webhook)
• Anda memisahkan pekerjaan antara tim frontend dan tim backend

REST adalah gaya yang paling umum, tetapi bukan satu-satunya. REST vs GraphQL menjelaskan kapan satu endpoint query yang fleksibel lebih cocok.

Rancang dulu: resource dan route

Tuliskan kata benda dalam aplikasi Anda dan apa yang dilakukan orang terhadapnya. Untuk aplikasi booking sederhana:

Route ini sesuai dengan create, read, update, dan delete; lihat apa itu CRUD. Konvensi yang layak diikuti:

• Kata benda jamak, tanpa kata kerja di URL: /bookings, bukan /getBookings.
• Bersarang hanya satu level jika itu memperjelas kepemilikan: /bookings/{id}/notes.
• Aksi di luar CRUD bisa dijadikan sub-resource: POST /bookings/{id}/cancel lebih jelas daripada PATCH yang samar.
• Penamaan yang konsisten untuk field, misalnya created_at di semua tempat.

Status code dan error

Gunakan kode HTTP standar agar client tahu apa yang terjadi tanpa perlu membaca teks:

Kembalikan error dalam satu bentuk JSON yang konsisten, misalnya {"error": {"code": "slot_taken", "message": "Waktu itu sudah tidak tersedia."}}, dan jangan pernah menyertakan stack trace atau error database dalam respons.

Pilihan dan trade-off

Langkah demi langkah

1. Daftarkan resource dan route seperti di atas, termasuk siapa yang boleh memanggil setiap route.
2. Modelkan data di database Anda dengan field dan relasi yang dibutuhkan.
3. Bangun route baca lebih dulu, lalu create, update, dan delete.
4. Validasi input pada setiap penulisan data dengan library skema: field wajib, tipe, panjang, dan nilai yang diizinkan. Tolak field yang tidak dikenal.
5. Tambahkan autentikasi, lalu otorisasi per data: membuka /bookings/42 harus memeriksa bahwa booking 42 milik pemanggil, bukan hanya bahwa seseorang sudah login.
6. Paginate setiap daftar dan batasi ukuran halaman.
7. Batasi rate untuk login dan route yang berat. Lihat rate limiting.
8. Atur CORS hanya jika browser dari domain lain harus memanggil API, dan daftarkan origin tersebut secara eksplisit. Cara memperbaiki error CORS menjelaskan error yang akan Anda temui.
9. Tulis dokumentasi dan tes untuk setiap route, termasuk kasus gagalnya.
10. Deploy dengan secret di environment variable, HTTPS, log, dan health check.

Prompt untuk AI builder Anda

Scaffold:

Buat REST API untuk booking dengan route berikut: GET /api/health, GET /api/bookings (dengan pagination, maksimal 50 per halaman), POST /api/bookings, GET /api/bookings/:id, PATCH /api/bookings/:id, DELETE /api/bookings/:id. Simpan data di database kami. Validasi body request dengan library skema dan tolak field yang tidak dikenal. Kembalikan error JSON dalam bentuk {"error": {"code", "message"}} dengan status code yang tepat (400, 401, 403, 404, 409). Simpan secret di environment variable.

Keamanan:

Wajibkan login di setiap route booking. Pada setiap pembacaan, pembaruan, dan penghapusan, periksa di server bahwa booking tersebut milik pengguna saat ini; kembalikan 404 jika bukan. Jangan pernah menerima ID pengguna atau role dari body request. Batasi POST /api/bookings menjadi 20 per menit per pengguna. Catat error di server tanpa mengembalikan stack trace.

Dokumentasi:

Tulis deskripsi OpenAPI untuk route ini, dan README singkat dengan contoh request dan respons untuk setiap route.

Menguji API Anda

Uji dari luar frontend, karena penyerang pun akan melakukannya:

• Setiap route berfungsi dengan input yang valid dan mengembalikan bentuk serta kode yang didokumentasikan
• Field yang hilang atau tidak valid mengembalikan 400 dengan pesan yang jelas
• Tanpa token, setiap route yang dilindungi mengembalikan 401
• Pengguna A yang meminta data milik pengguna B berdasarkan ID mendapat 404 atau 403
• Daftar di-paginate; limit yang sangat besar dibatasi
• Create yang duplikat atau bertentangan mengembalikan 409, bukan 500
• Batas rate mengembalikan 429
• Respons error tidak berisi stack trace, SQL, atau secret
• CORS hanya mengizinkan origin yang Anda maksudkan

Kesalahan umum

• Memeriksa login tetapi tidak kepemilikan. Ini celah API yang paling umum: pengguna mana pun yang sudah login bisa membaca data apa pun dengan mengubah ID.
• Mempercayai client. Harga, role, dan ID pengguna dari body request bisa diubah.
• Mengembalikan seluruh baris database. Hash password dan field internal ikut bocor. Pilih apa yang disertakan dalam setiap respons.
• Daftar tanpa batas. Satu request untuk semua data bisa memperlambat seluruh aplikasi.
• 200 OK dengan pesan error di dalamnya. Client dan monitoring tidak bisa tahu bahwa request gagal.
• CORS diset untuk mengizinkan semua pada API yang memakai cookie.
• Tidak ada health check atau log, sehingga Anda baru tahu ada gangguan dari keluhan pengguna.

Untuk pemeriksaan yang lebih luas sebelum rilis, lihat checklist keamanan untuk aplikasi yang dibuat dengan AI.

Membangun REST API di Mythex

Anda bisa meminta Mythex membuat API sebagai bagian dari aplikasi atau sebagai layanan tersendiri. Resep dokumentasi REST API backend berisi prompt awal: sebutkan framework dan route Anda, minta error JSON yang jelas, simpan secret di environment variable, dan sertakan Dockerfile. Backend container di Node, Python, C#, Java, dan lainnya dipublikasikan lewat Dockerfile, dan Mythex menangani deploy dari Publish (API backend). Sebuah proyek bisa menjalankan website dan server API berdampingan, dan Anda bisa berpindah di antara keduanya dalam preview. Simpan kunci sebagai secret proyek, dan jika API membutuhkan database, minta di chat. Untuk pekerjaan terjadwal di sekitar API Anda, lihat cara menjalankan background job.

Pertanyaan