REST API Design Best Practices — txt1.ai

Oleh Marcus Chen, Arsitek API Utama dengan 14 tahun pengalaman membangun sistem yang dapat diskalakan di perusahaan fintech dan kesehatan

Tiga tahun yang lalu, saya menyaksikan sebuah startup menghabiskan $2,3 juta untuk biaya rekayasa karena desain API mereka pada dasarnya rusak. Mereka telah membangun sistem pemrosesan pembayaran dengan 47 titik akhir yang berbeda, konvensi penamaan yang tidak konsisten, dan tidak memiliki strategi versi. Ketika mereka perlu menambahkan fitur baru untuk klien terbesar mereka, perubahan tersebut mengalir melalui seluruh sistem mereka seperti domino. Enam bulan refactoring kemudian, mereka kehilangan pelanggan terbesar mereka dan memberhentikan 40% dari tim rekayasa mereka.

Musibah itu mengajarkan saya sesuatu yang krusial: desain API bukan hanya tentang membuat sesuatu bekerja hari ini. Ini adalah tentang membangun kontrak antara sistem Anda dan dunia yang dapat berevolusi dengan baik selama bertahun-tahun, menangani jutaan permintaan, dan tetap cukup intuitif agar pengembang benar-benar ingin menggunakannya. Setelah menghabiskan lebih dari satu dekade merancang API yang memproses miliaran transaksi setiap tahun, saya telah belajar bahwa perbedaan antara API yang baik dan yang hebat sering kali bergantung pada sejumlah prinsip dasar yang sering diabaikan oleh sebagian besar tim.

Fondasi: Memahami REST di Balik Kata Kunci

Ketika saya memulai karir saya pada tahun 2010, REST sudah menjadi gaya arsitektur dominan untuk API web, tetapi saya memperhatikan bahwa banyak pengembang memperlakukannya seperti daftar periksa daripada filosofi. REST adalah singkatan dari Representational State Transfer, dan dibangun di atas enam batasan inti yang diuraikan oleh Roy Fielding dalam disertasi doktornya. Tapi inilah yang penting dalam praktik: REST adalah tentang memperlakukan sumber daya API Anda sebagai kata benda, menggunakan metode HTTP sebagai kata kerja, dan mempertahankan keadaan tanpa status.

Prinsip keadaan tanpa status saja telah menghemat banyak waktu debugging saya. Setiap permintaan dari klien ke server harus memuat semua informasi yang diperlukan untuk memahami dan memproses permintaan tersebut. Tidak ada status sesi di server. Ini berarti API Anda dapat diskalakan secara horizontal tanpa manajemen sesi yang kompleks, dan server mana pun di kluster Anda dapat menangani permintaan mana pun. Ketika saya merancang API pembayaran untuk platform kesehatan yang memproses 3,2 juta transaksi harian, prinsip ini memungkinkan kami untuk berkembang dari 4 server menjadi 47 selama periode puncak tanpa mengubah satu baris kode aplikasi pun.

Tetapi REST bukan dogma. Saya telah melihat tim menghabiskan waktu berbulan-bulan berdiskusi tentang apakah sesuatu itu "benar-benar RESTful" ketika mereka seharusnya fokus pada konsistensi dan kegunaan. Tujuannya adalah untuk membuat API yang dapat dipahami pengembang secara intuitif. Jika Anda menggunakan metode HTTP dengan benar, mengorganisir sumber daya secara logis, dan mempertahankan keadaan tanpa status, Anda sudah 90% dari jalan raya. 10% sisanya adalah tentang pola praktis yang membuat API Anda menyenangkan untuk digunakan, bukan sumber frustrasi.

Penamaan Sumber Daya: Seni URL Intuitif

Struktur URL Anda adalah hal pertama yang dilihat oleh pengembang, dan itu menetapkan ekspektasi untuk seluruh API Anda. Saya mengikuti aturan sederhana: gunakan kata benda untuk sumber daya, jaga agar tetap jamak, dan atur mereka secara hierarkis saat ada hubungan orangtua-anak yang jelas. Misalnya, /api/v1/users/12345/orders/67890 langsung memberi tahu Anda bahwa Anda melihat pesanan 67890 yang dimiliki oleh pengguna 12345.

"API terbaik adalah yang dapat diprediksi oleh pengembang endpoint berikutnya sebelum membaca dokumentasi Anda—itulah saat Anda tahu Anda telah mencapai konsistensi yang sebenarnya."

Di sinilah sebagian besar tim melakukan kesalahan: mereka mencampur kata kerja ke dalam URL mereka. Saya telah meninjau API dengan titik akhir seperti /api/getUser atau /api/createOrder. Ini berlebihan karena metode HTTP sudah menyediakan kata kerja. GET /api/users/12345 lebih jelas dan lebih RESTful daripada GET /api/getUser/12345. Metode HTTP memberi tahu Anda tindakan apa yang sedang Anda lakukan; URL memberi tahu Anda sumber daya mana yang sedang Anda lakukan.

Konsistensi lebih penting daripada kesempurnaan. Dalam satu proyek, kami memiliki debat tentang apakah akan menggunakan /users atau /accounts untuk sumber daya pengguna kami. Kami menghabiskan tiga jam dalam pertemuan itu. Yang penting bukanlah istilah mana yang kami pilih, tetapi bahwa kami memilih salah satu dan tetap menggunakannya di seluruh API. Kami mendokumentasikan keputusan kami, menambahkannya ke panduan gaya API kami, dan melanjutkan. Konsistensi itu berarti pengembang dapat memprediksi nama endpoint tanpa terus-menerus memeriksa dokumentasi.

Untuk sumber daya bersarang, saya membatasi kedalaman maksimum dua atau tiga tingkat. Di luar itu, URL menjadi tidak praktis dan hubungan menjadi tidak jelas. Jika Anda menemukan diri Anda menulis /api/companies/123/departments/456/teams/789/members/012, Anda telah melampaui batas. Sebagai gantinya, pertimbangkan untuk menjadikan tim sebagai sumber daya tingkat atas dengan parameter kueri: /api/teams/789/members?company=123&department=456. Ini menjaga URL tetap dapat dikelola sambil tetap memungkinkan Anda menyaring dan membatasi sumber daya dengan tepat.

Metode HTTP: Menggunakan Alat yang Tepat untuk Pekerjaan

HTTP memberi kita kosakata kaya metode, tetapi saya melihat pengembang terus-menerus menyalahgunakannya atau membatasi diri mereka hanya pada GET dan POST. Memahami makna semantik setiap metode telah membantu saya membangun API yang intuitif dan dapat dicache. GET mengambil sumber daya dan harus idempotent dan aman—memanggilnya beberapa kali menghasilkan hasil yang sama tanpa efek samping. POST membuat sumber daya baru. PUT menggantikan seluruh sumber daya. PATCH memperbarui bagian dari sumber daya. DELETE menghapus sumber daya.

Idempotensi PUT dibandingkan POST sangat penting untuk keandalan. Ketika saya membangun API manajemen inventaris untuk jaringan ritel dengan 847 toko, kami menggunakan PUT untuk pembaruan secara khusus karena jaminan idempotensinya. Jika gangguan jaringan menyebabkan permintaan dikirim dua kali, PUT memastikan kami tidak secara tidak sengaja membuat catatan duplikat atau menerapkan pembaruan yang sama beberapa kali. Keputusan tunggal ini mencegah perkiraan 12.000 perbedaan inventaris pada tahun pertama operasional.

PATCH kurang dimanfaatkan tetapi sangat berharga. Alih-alih mengharuskan klien untuk mengirim seluruh representasi sumber daya untuk pembaruan kecil, PATCH memungkinkan pembaruan parsial. Ketika memperbarui profil pengguna dengan 30 kolom, mengapa memaksa klien untuk mengirim semua 30 ketika mereka hanya ingin mengubah alamat email? PATCH /api/users/12345 dengan tubuh {"email": "[email protected]"} lebih efisien dan kurang rentan terhadap kesalahan daripada memerlukan sumber daya lengkap.

DELETE juga harus idempotent. Memanggil DELETE pada sumber daya yang sudah dihapus harus mengembalikan 204 No Content atau 404 Not Found, bukan kesalahan. Ini membuat logika pengulangan lebih sederhana dan lebih dapat diandalkan. Saya telah menerapkan penghapusan lembut di mana DELETE menandai sumber daya sebagai tidak aktif daripada secara fisik menghapusnya, yang memberikan jejak audit dan memungkinkan pemulihan. Kuncinya adalah bahwa panggilan DELETE berikutnya ke sumber daya yang sama menghasilkan hasil yang sama—sumber daya itu hilang dari perspektif klien.

Kode Status: Berbicara dalam Bahasa HTTP dengan Fasih