REST API Design: 10 Principles for Clean APIs — cod-ai.com

Saya masih ingat hari ketika saya harus menjelaskan kepada CEO kami mengapa aplikasi mobile kami menghabiskan paket data pengguna seperti kebakaran hutan. Itu tahun 2016, dan saya telah menjalani tiga tahun di peran saya sebagai Arsitek API Utama di sebuah startup fintech. API REST kami mengirimkan seluruh objek pengguna—lengkap dengan foto profil yang terenkode dalam base64—setiap kali aplikasi memeriksa saldo akun. Kami kehilangan pelanggan, dan saya telah merancang API yang menyebabkan kerugian ini.

Pelajaran menyakitkan itu mengajarkan saya sesuatu yang penting: desain API REST bukan hanya tentang membuat semuanya berfungsi. Ini tentang membuatnya berfungsi dengan baik, pada skala, dalam kondisi dunia nyata yang tidak pernah disebutkan dalam buku teks. Selama dua belas tahun terakhir membangun API untuk perusahaan mulai dari startup dengan 10 orang hingga perusahaan Fortune 500, saya telah melihat kesalahan yang sama diulang berkali-kali—dan saya telah melakukan sebagian besar dari kesalahan itu sendiri.

Sekarang, saya akan membagikan sepuluh prinsip yang mengubah cara saya merancang API. Ini bukan konsep teoretis dari makalah akademis. Ini adalah panduan yang telah teruji dalam lingkungan produksi yang melayani jutaan permintaan per hari. Apakah Anda sedang membangun API pertama Anda atau melakukan refactoring pada yang kesepuluh, prinsip-prinsip ini akan membantu Anda menciptakan antarmuka yang benar-benar ingin digunakan oleh pengembang.

Prinsip 1: Rancang API Anda Seperti Produk, Bukan Pembungkus Database

Kesalahan terbesar yang saya lihat dalam desain API REST adalah menganggap API sebagai lapisan tipis di atas tabel database. Saya telah meninjau ratusan API di mana titik akhir mencerminkan satu-satu dengan skema database, mengungkapkan detail implementasi internal yang seharusnya tidak pernah terlihat. Pendekatan ini menciptakan antarmuka yang rapuh yang rusak setiap kali model data Anda berkembang.

Ketika saya bergabung dengan perusahaan saya saat ini sebagai VP Rekayasa Platform, API kami memiliki 47 titik akhir yang langsung mencerminkan skema PostgreSQL kami. Mengubah satu nama kolom membutuhkan koordinasi pembaruan di 23 aplikasi klien yang berbeda. Utang teknis membatasi kemampuan kami untuk berinovasi.

Sebagai gantinya, pikirkan API Anda sebagai produk dengan siklus hidupnya sendiri, strategi versi, dan pertimbangan pengalaman pengguna. Konsumen API Anda tidak peduli dengan strategi normalisasi database Anda atau arsitektur mikroservis internal Anda. Mereka peduli tentang menyelesaikan tugas spesifik dengan efisien.

Misalnya, daripada mengekspos titik akhir terpisah untuk /users, /user_profiles, /user_preferences, dan /user_settings, pertimbangkan apa yang benar-benar dibutuhkan oleh konsumen API Anda. Dalam banyak kasus, mereka ingin titik akhir cohesif /users/{id} yang mengembalikan sumber daya yang dirancang dengan baik. Gunakan parameter kueri seperti ?fields=profile,preferences untuk membiarkan konsumen meminta persis apa yang mereka butuhkan.

Saya menerapkan pendekatan ini di sebuah perusahaan SaaS kesehatan di mana kami mengurangi area permukaan API kami dari 89 titik akhir menjadi 34 sambil benar-benar meningkatkan fungsionalitas. Waktu respons turun sebesar 43% karena kami menghilangkan interaksi yang berlebihan yang disebabkan oleh memerlukan banyak permintaan untuk mengumpulkan informasi dasar. Yang lebih penting, dokumentasi API kami menjadi dapat dipahami, dan waktu onboarding pengembang turun dari dua minggu menjadi tiga hari.

Kuncinya adalah memahami model domain API Anda, yang mungkin berbeda secara signifikan dari model persistensi Anda. Luangkan waktu dengan konsumen API Anda—baik mereka adalah tim frontend internal atau mitra eksternal—dan pahami alur kerja mereka. Rancang sumber daya berdasarkan model mental mereka, bukan tabel database Anda.

Prinsip 2: Terima Kode Status HTTP Dengan Benar (Tapi Jangan Terlalu Dipikirkan)

Kode status HTTP adalah garis komunikasi pertama API Anda dengan klien, namun saya terus melihatnya disalahgunakan atau diabaikan sepenuhnya. Saya pernah melakukan audit pada API yang mengembalikan 200 OK untuk setiap respons, termasuk kesalahan, dengan status yang sebenarnya terkubur dalam field JSON. Para pengembang berpikir mereka membantu dengan "selalu berhasil," tetapi sebenarnya mereka merusak penanganan kesalahan di setiap pustaka klien HTTP.

Anda tidak perlu menghafal semua 63 kode status HTTP, tetapi Anda harus menggunakan kode inti dengan benar. Berikut adalah pemecahan praktik saya berdasarkan dua belas tahun pengalaman produksi:

• 200 OK: GET, PUT, atau PATCH yang berhasil yang mengembalikan konten
• 201 Created: POST yang berhasil yang membuat sumber daya (sertakan header Lokasi)
• 204 No Content: DELETE atau pembaruan yang berhasil yang tidak mengembalikan apa pun
• 400 Bad Request: Klien mengirimkan data tidak valid (sertakan kesalahan validasi spesifik)
• 401 Unauthorized: Autentikasi diperlukan atau gagal
• 403 Forbidden: Sudah terautentikasi tetapi tidak memiliki izin
• 404 Not Found: Sumber daya tidak ada
• 409 Conflict: Permintaan berbenturan dengan keadaan saat ini (pembuatan duplikat, ketidakcocokan versi)
• 422 Unprocessable Entity: Secara sintaksis benar tetapi semantik tidak valid
• 429 Too Many Requests: Batas tarif terlampaui (sertakan header Retry-After)
• 500 Internal Server Error: Sesuatu yang rusak di pihak Anda
• 503 Service Unavailable: Gangguan sementara atau pemeliharaan

Perbedaan antara 401 dan 403 membingungkan banyak pengembang. Anggaplah 401 sebagai "Saya tidak tahu siapa Anda" dan 403 sebagai "Saya tahu siapa Anda, tetapi Anda tidak bisa melakukan itu." Ini penting karena memberi tahu klien apakah mengautentikasi ulang mungkin membantu.

Demikian pula, 400 versus 422 adalah hal yang halus tetapi berguna. Gunakan 400 untuk JSON yang tidak terformat dengan benar atau field yang diperlukan yang hilang—hal-hal yang gagal dalam pemrosesan dasar. Gunakan 422 untuk pelanggaran logika bisnis seperti mencoba mentransfer uang lebih banyak dari yang ada di akun. Perbedaan ini membantu klien mengkategorikan kesalahan dengan tepat.

Di perusahaan sebelumnya, kami menerapkan penggunaan kode status yang tepat dan melihat tiket dukungan kami terkait kesalahan API menurun sebanyak 67% di kuartal pertama. Para pengembang akhirnya dapat mengandalkan semantik HTTP standar daripada menganalisis isi respons untuk menentukan keberhasilan atau kegagalan.

Prinsip 3: Versikan API Anda Sejak Hari Pertama (Dan Lakukan Dengan Benar)

Saya belajar pelajaran ini dengan cara yang sulit. Pada tahun 2014, saya meluncurkan sebuah API tanpa versi karena "kami hanya akan mempertahankan kompatibilitas mundur selamanya." Enam bulan kemudian, kami perlu melakukan perubahan yang memengaruhi untuk mendukung kebutuhan bisnis yang kritis. Kami memiliki 1.200 konsumen API aktif tanpa cara untuk memigrasi mereka secara bertahap. Hasilnya adalah peningkatan yang dipaksa yang merusak