REST API Design: 10 Principles for Clean APIs — txt1.ai

Tiga tahun menjabat sebagai Arsitek API Utama di sebuah unicorn fintech, saya menyaksikan aplikasi mobile kami mengalami kerusakan yang spektakuler selama demo produk kepada investor. Penyebabnya? Sebuah endpoint API yang mengembalikan 47MB JSON karena seseorang berpikir "semakin banyak data selalu lebih baik." Momen yang memalukan itu—dan keterlambatan pendanaan $2 juta yang ditimbulkannya—mengajarkan saya bahwa desain API bukan hanya tentang membuat segalanya berfungsi. Ini tentang membuatnya berfungsi dengan elegan, dapat diprediksi, dan berkelanjutan pada skala besar.

Saya Marcus Chen, dan saya telah menghabiskan 12 tahun terakhir merancang API yang menangani segalanya dari 50 permintaan per hari hingga 50 juta. Saya telah melihat insinyur yang brilian menciptakan API yang begitu rumit sehingga bahkan mereka tidak dapat mengingat cara menggunakannya enam bulan kemudian. Saya juga telah melihat pengembang junior membuat antarmuka yang begitu intuitif sehingga dokumentasi hampir tidak diperlukan. Perbedaannya? Komitmen terhadap prinsip dasar yang melampaui kerangka kerja, bahasa, dan tren arsitektur.

Saya membagikan 10 prinsip yang telah membimbing setiap API sukses yang saya bangun—prinsip-prinsip yang dibentuk melalui insiden produksi, umpan balik pengguna, dan banyak tinjauan kode. Ini bukan ideal teoretis; ini adalah pedoman yang telah diuji di lapangan yang telah menghemat ratusan jam untuk tim saya dan mencegah banyak masalah integrasi.

Fondasi: Memahami REST di Balik Kata Trend

Sebelum menyelami prinsip-prinsip tertentu, mari kita hadapi satu kebenaran yang tidak nyaman: sebagian besar "REST API" sebenarnya tidak RESTful. Mereka adalah API HTTP dengan respons JSON, yang baik-baik saja, tetapi menyebutnya REST adalah seperti menyebut sepeda sebagai sepeda motor karena keduanya memiliki roda. Disertasi asli REST oleh Roy Fielding menguraikan enam batasan, dan sebagian besar API melanggar setidaknya tiga dari batasan tersebut.

Ini yang penting dalam praktik: REST adalah gaya arsitektur yang memperlakukan API Anda sebagai kumpulan sumber daya, masing-masing diidentifikasi oleh URL, dimanipulasi melalui metode HTTP standar. Keindahan pendekatan ini adalah prediktabilitasnya. Ketika saya melihat GET /users/123, saya tahu persis apa yang dilakukannya tanpa membaca dokumentasi. Ketika saya melihat POST /users, saya tahu itu membuat pengguna baru. Konsistensi ini adalah kekuatan super REST.

Dalam pengalaman saya, tim yang benar-benar memahami prinsip REST mengirim API 40% lebih cepat daripada mereka yang menganggapnya sebagai centang pada daftar. Mengapa? Karena REST menyediakan model mental yang membimbing keputusan desain. Haruskah ini menjadi endpoint baru atau parameter kueri? REST menjawab itu. Haruskah ini menjadi POST atau PUT? REST memberi tahu Anda. Prinsip-prinsip itu bukanlah batasan—mereka adalah penyangga yang menjaga Anda tetap berada di jalur menuju API yang dapat dipelihara dan dapat diskalakan.

Saya telah meninjau lebih dari 200 desain API selama karir saya, dan yang bertahan lama semuanya memiliki satu karakteristik: mereka menghormati pemikiran berbasis sumber daya REST. Yang menjadi mimpi buruk dalam pemeliharaan? Mereka menganggap REST sebagai saran ketimbang kerangka kerja. API Anda akan hidup lebih lama dari yang Anda harapkan—mungkin 5-7 tahun minimal dalam produksi. Rancanglah dengan mempertimbangkan umur panjang itu.

Prinsip 1: Sumber Daya Adalah Kata Benda, Bukan Kata Kerja

Prinsip ini tampak jelas sampai Anda melihat pelanggaran dunia nyata. Saya pernah mewarisi API dengan endpoint seperti /getUser, /createOrder, dan /deleteProduct. Setiap operasi adalah kata kerja di URL, menjadikan metode HTTP redundan. API tersebut memiliki 127 endpoint melakukan apa yang seharusnya bisa dilakukan oleh 23 endpoint berbasis sumber daya dengan lebih baik.

Inilah aturannya: URL Anda harus mewakili benda (sumber daya), dan metode HTTP harus mewakili tindakan pada benda-benda tersebut. Alih-alih menggunakan POST /createUser, gunakan POST /users. Alih-alih GET /getUserOrders, gunakan GET /users/123/orders. Ini bukan sekadar pedantri—ini tentang menciptakan model mental yang konsisten yang dapat diskalakan.

Perhatikan beban kognitif. Dengan URL berbasis kata kerja, pengembang harus mengingat nama endpoint yang sewenang-wenang. Dengan URL berbasis sumber daya, mereka mengikuti pola. Dalam aplikasi fintech kami, kami mengurangi waktu onboarding untuk pengembang baru dari 3 minggu menjadi 1,5 minggu hanya dengan merombak nama sumber daya yang tepat. API menjadi self-documenting.

Tentu ada pengecualian. Tindakan yang tidak pas dengan operasi CRUD—seperti POST /payments/123/refund atau POST /orders/456/cancel—dapat diterima. Ini adalah endpoint gaya pengendali, dan itu baik-baik saja ketika alternatifnya akan menjadi canggung. Kuncinya adalah menggunakannya secara hemat dan konsisten. Dalam API kami saat ini, 89% endpoint adalah operasi sumber daya murni, dan 11% sisanya adalah tindakan pengendali yang jelas didokumentasikan.

Saat menamai sumber daya, gunakan kata benda jamak secara konsisten. /users bukan /user, /orders bukan /order. Ya, GET /users/123 mengembalikan satu pengguna, dan itu mungkin terasa aneh secara tata bahasa, tetapi konsistensi mengalahkan tata bahasa. Saya telah melihat tim menghabiskan berjam-jam memperdebatkan tunggal vs. jamak; pilih jamak dan lanjutkan.

Prinsip 2: Metode HTTP Memiliki Makna Tersendiri

HTTP memberikan kita kosakata yang kaya: GET, POST, PUT, PATCH, DELETE, dan lainnya. Masing-masing memiliki semantik tertentu, dan menghormati semantik tersebut membuat API Anda dapat diprediksi dan dapat di-cache. Namun, saya sering melihat API di mana POST melakukan segalanya—membuat, memperbarui, menghapus, bahkan mengambil data. Ini seperti menggunakan palu untuk setiap tugas pertukangan karena Anda tidak ingin mempelajari alat lain.

Permintaan GET haruslah aman dan idempotent. Aman berarti mereka tidak mengubah status server. Idempotent berarti memanggilnya beberapa kali menghasilkan hasil yang sama. Ini bukan akademis—itu memungkinkan caching, yang dapat mengurangi beban server Anda hingga 60-80% untuk API yang banyak dibaca. Ketika saya mengoptimalkan API profil pengguna kami dengan menerapkan semantik GET dan caching HTTP dengan baik, biaya server kami turun sebesar $4.200 setiap bulan.

POST membuat sumber daya baru. Ini tidak aman dan tidak idempotent—memanggilnya dua kali akan membuat dua sumber daya. PUT menggantikan seluruh sumber daya dan idempotent—memanggilnya sepuluh kali memiliki efek yang sama seperti memanggilnya sekali. PATCH memperbarui sebagian sumber daya dan harus idempotent. DELETE menghapus sebuah sumber daya dan idempotent. Perbedaan ini penting untuk logika pengulangan klien, strategi caching, dan konfigurasi gateway API.

Berikut adalah contoh praktis dari API pemrosesan pembayaran kami. Awalnya kami menggunakan POST untuk segalanya, termasuk pemeriksaan status pembayaran. Ketika masalah jaringan menyebabkan klien mengulangi permintaan, kami membuat catatan pembayaran duplikat. Setelah merombak untuk menggunakan GET untuk pemeriksaan status dan menerapkan kunci idempotensi yang tepat untuk permintaan POST, pembayaran duplikat turun dari 2,3% menjadi 0,01% dari transaksi. Itu adalah uang yang nyata yang dihemat dan kepercayaan pelanggan yang terjaga.

Satu pertanyaan umum: kapan Anda harus menggunakan PUT vs. PATCH? Gunakan PUT ketika klien mengirimkan representasi sumber daya yang lengkap. Gunakan PATCH saat klien hanya mengirimkan bidang yang ingin diubah. Dalam praktiknya, PATCH biasanya lebih tepat karena klien jarang ingin mengirimkan setiap bidang. Analitik kami menunjukkan bahwa 94% dari operasi pembaruan kami menggunakan PATCH, dan ini membuat aplikasi mobile kami lebih efisien dengan mengurangi ukuran payload rata-rata sebesar 73%.

Prinsip 3: Kode Status Adalah Protokol Komunikasi Anda

Kode status HTTP adalah bahasa yang distandarisasi untuk komunikasi