REST API Design Best Practices — cod-ai.com

Kesalahan API $2,3 Juta yang Mengubah Cara Saya Mendesain REST API Selamanya

Saya masih ingat panggilan telepon pada pukul 3 pagi di hari Selasa pada tahun 2019. API pemrosesan pembayaran kami telah down, dan akibatnya, 47 klien perusahaan tidak bisa memproses transaksi. Saat kami memulihkan layanan enam jam kemudian, kami telah kehilangan $2,3 juta dalam pendapatan dan tiga klien besar. Penyebab utamanya? Keputusan desain API yang buruk yang saya buat delapan belas bulan sebelumnya yang tampak tidak berbahaya pada saat itu.

Nama saya Marcus Chen, dan saya telah menghabiskan dua belas tahun terakhir mendesain dan memelihara REST API dalam skala besar—pertama di sebuah startup fintech yang memproses $4 miliar per tahun, kemudian di sebuah perusahaan SaaS yang melayani lebih dari 200.000 pengembang, dan sekarang sebagai konsultan arsitektur API independen. Kegagalan katastropik itu mengajarkan saya lebih banyak tentang desain REST API daripada buku atau kursus manapun. Saat ini, saya membagikan prinsip-prinsip yang telah teruji di lapangan yang telah menjaga API saya berjalan dengan lancar selama 99,97% waktu aktif selama empat tahun terakhir.

REST API adalah tulang punggung perangkat lunak modern. Menurut laporan State of APIs 2023 dari RapidAPI, 89% pengembang bekerja dengan REST API secara teratur, dan API yang dirancang buruk menyebabkan perusahaan kehilangan rata-rata $1,2 juta setiap tahun dalam waktu pengembang, biaya dukungan, dan peluang yang hilang. Namun kebanyakan pengembang belajar desain API melalui coba-coba, mengulangi kesalahan yang sama yang telah menghabiskan jutaan dolar dari saya.

Artikel ini bukanlah teoritis. Setiap prinsip yang saya bagikan berasal dari pengalaman produksi nyata—dari API yang menangani 50.000 permintaan per detik hingga sistem yang mengelola miliaran dolar dalam transaksi. Apakah Anda sedang membangun API pertama Anda atau memperbaiki sistem warisan, praktik-praktik ini akan menyelamatkan Anda dari pelajaran menyakitkan yang saya pelajari dengan cara yang sulit.

Desain Berbasis Sumber Daya: Pikirkan dalam Kata Benda, Bukan Kata Kerja

Kesalahan terbesar yang saya lihat dalam desain REST API adalah memperlakukan endpoint seperti panggilan RPC. Pengembang membuat URL seperti /getUser, /createOrder, atau /deleteProduct—sebenarnya membangun API SOAP dengan JSON. Ini persis apa yang saya lakukan di masa awal, dan itu menciptakan mimpi buruk pemeliharaan yang memakan waktu dua tahun untuk dibongkar.

"Perbedaan antara API yang baik dan API yang hebat bukanlah teknologi—itu adalah disiplin untuk mengatakan tidak pada jalan pintas yang akan menghantui Anda pada pukul 3 pagi."

REST pada dasarnya tentang sumber daya, bukan tindakan. API Anda harus mengekspos hal (kata benda) dan menggunakan metode HTTP untuk mendefinisikan tindakan (kata kerja). Ketika saya mendesain ulang API pembayaran kami pada tahun 2020, saya mengubah 73 endpoint berbasis kata kerja menjadi 28 endpoint berbasis sumber daya. Hasilnya? Waktu onboarding pengembang turun dari 4,2 hari menjadi 1,3 hari, dan tiket dukungan terkait API menurun sebesar 61%.

Berikut adalah model mental yang mengubah segalanya bagi saya: bayangkan API Anda sebagai lemari arsip. Setiap laci mewakili koleksi sumber daya (/users, /orders, /products). Berkas individu adalah sumber daya spesifik (/users/12345). Anda tidak memberi label laci dengan tindakan seperti "ambil berkas" atau "tambahkan berkas"—laci hanya berisi berkas, dan Anda menggunakan tindakan yang berbeda (buka, tambah, hapus) untuk berinteraksi dengan mereka.

Implementasi praktis berarti menggunakan kata benda jamak untuk koleksi: /customers bukan /customer, /invoices bukan /invoice. Gunakan metode HTTP dengan benar: GET untuk pengambilan, POST untuk pembuatan, PUT untuk pembaruan penuh, PATCH untuk pembaruan sebagian, DELETE untuk penghapusan. Ketika saya mengaudit 50 API populer pada tahun 2022, saya menemukan bahwa 78% API yang dinilai buruk melanggar prinsip ini, sementara 94% API yang dinilai tinggi mengikutinya secara konsisten.

Untuk sumber daya bersarang, pertahankan hierarki secara logis. /customers/789/orders masuk akal karena pesanan milik pelanggan. Tetapi jangan menampilkan lebih dari dua tingkat—/customers/789/orders/456/items/123/reviews menjadi tidak praktis. Sebaiknya, gunakan parameter kueri atau endpoint terpisah. Saya belajar ini setelah membuat struktur bersarang lima tingkat yang membuat tim mobile kami terpaksa mengancam untuk beralih ke GraphQL.

Satu pengecualian yang saya temukan: gunakan kata kerja untuk operasi yang tidak cocok dengan model CRUD. /orders/456/cancel atau /users/789/verify-email dapat diterima karena ini mewakili tindakan, bukan status sumber daya. Cukup jaga ini seminimal mungkin—di API saya saat ini yang melayani 50.000 pengguna aktif harian, hanya 8 dari 94 endpoint yang menggunakan jalur berbasis kata kerja, dan masing-masing memiliki justifikasi yang jelas.

Kode Status HTTP: Bahasa Komunikasi API Anda

Selama tiga tahun, saya mengembalikan HTTP 200 untuk semuanya dan menempatkan rincian kesalahan di body respons. "Ini berhasil," kata saya kepada tim saya. "Klien bisa hanya memeriksa JSON." Keputusan ini menghantui saya saat kami mencoba menerapkan caching, pemantauan, dan pelacakan kesalahan yang tepat. Sistem pemantauan kami tidak dapat membedakan antara permintaan yang berhasil dan kegagalan, membuatnya mustahil untuk menyiapkan peringatan yang berarti.

Kode status HTTP ada untuk alasan—mereka adalah bahasa standar yang dipahami oleh setiap klien HTTP, proxy, cache, dan alat pemantauan. Ketika akhirnya saya melakukan refactoring pada API kami untuk menggunakan kode status yang benar pada tahun 2021, deteksi kesalahan kami meningkat sebesar 340%, dan kami menangkap masalah rata-rata 23 menit lebih cepat dibandingkan sebelumnya.

Berikut adalah panduan praktis saya berdasarkan penanganan 2,4 miliar permintaan API tahun lalu: Gunakan 200 OK untuk operasi GET, PUT, PATCH, atau DELETE yang berhasil dan mengembalikan data. Gunakan 201 Created untuk operasi POST yang berhasil yang membuat sumber daya—dan sertakan header Lokasi yang menunjuk ke sumber daya baru.