Figure 1. Merancang dokumen  (sumber: pexels.com)

Di ekosistem digital saat ini, API (Application Programming Interface) adalah tulang punggung yang menghubungkan berbagai layanan dan aplikasi. Namun, tidak semua API diciptakan sama. Ada API yang membingungkan dan membuat frustrasi, dan ada API yang intuitif, mudah digunakan, dan menjadi favorit para developer.

Sebuah API pada dasarnya adalah produk untuk developer. Pengalaman pengguna menjadi faktor penentu keberhasilannya. API yang dirancang dengan baik akan mempercepat proses development, mengurangi bug, dan mempermudah adopsi.

Berikut adalah prinsip-prinsip kunci untuk merancang RESTful API yang bersih, konsisten, dan dicintai oleh para penggunanya: developer.

 

  1. Gunakan Kata Benda (Nouns), Bukan Kata Kerja (Verbs) di URI

Prinsip paling fundamental dari REST adalah URI (Uniform Resource Identifier) merepresentasikan resource (sumber daya). Karena itu, gunakan kata benda jamak untuk menamai resource Anda. Operasi terhadap resource tersebut ditentukan oleh HTTP Verb yang digunakan.

  • Buruk: GET /getAllUsers atau POST /createNewUser
  • Baik: GET /users atau POST /users

Dengan pendekatan ini, satu URI (/users) dapat melayani berbagai macam operasi:

  • GET /users: Mengambil daftar semua pengguna.
  • POST /users: Membuat pengguna baru.
  • GET /users/{id}: Mengambil satu pengguna spesifik.
  • PUT /users/{id}: Memperbarui seluruh data pengguna.
  • DELETE /users/{id}: Menghapus pengguna.

 

  1. Manfaatkan HTTP Verb dengan Benar

HTTP menyediakan metode (verb) yang sudah memiliki makna semantik. Menggunakannya dengan benar membuat API Anda menjadi lebih ekspresif dan prediktif.

  • GET: Untuk membaca data. Operasi GET harus aman (safe) dan idempotent (menjalankannya berkali-kali tidak mengubah keadaan server).
  • POST: Untuk membuat resource baru. Menjalankan POST yang sama berkali-kali akan membuat beberapa resource baru.
  • PUT: Untuk memperbarui resource secara keseluruhan. Jika resource belum ada, PUT bisa juga membuatnya. Operasi ini bersifat idempotent.
  • PATCH: Untuk memperbarui sebagian kecil dari resource. Misalnya, hanya mengubah nama pengguna tanpa mengirim ulang seluruh data pengguna.
  • DELETE: Untuk menghapus resource.

 

  1. Gunakan Kode Status HTTP yang Sesuai

Jangan hanya mengandalkan 200 OK untuk semua respons yang berhasil. Kode status HTTP memberikan informasi cepat dan standar mengenai hasil dari sebuah permintaan.

  • 200 OK: Permintaan berhasil (umumnya untuk GET dan PATCH).
  • 201 Created: Resource baru berhasil dibuat (setelah POST). Sertakan header Location dengan URL ke resource baru tersebut.
  • 204 No Content: Permintaan berhasil namun tidak ada data untuk dikembalikan (umumnya setelah DELETE berhasil).
  • 400 Bad Request: Permintaan tidak valid karena kesalahan di sisi klien (misalnya, format JSON salah atau parameter hilang).
  • 401 Unauthorized: Klien tidak terautentikasi (belum login).
  • 403 Forbidden: Klien terautentikasi, tetapi tidak memiliki izin untuk mengakses resource ini.
  • 404 Not Found: Resource yang diminta tidak ditemukan.
  • 500 Internal Server Error: Terjadi kesalahan di sisi server yang tidak terduga.

 

  1. Sediakan Fitur Filtering, Sorting, dan Pagination

Untuk resource koleksi (seperti GET /articles), hampir tidak mungkin mengembalikan semua data sekaligus. Sediakan cara bagi klien untuk membatasi dan menavigasi data.

  • Filtering: GET /articles?status=published&author_id=123
  • Sorting : GET /articles?sort=-createdAt (tanda minus – berarti descending).
  • Pagination: GET /articles?page=2&limit=25

Membungkus respons dalam sebuah “amplop” (envelope) juga praktik yang baik untuk menyertakan metadata paginasi.

Figure 2. Contoh respon yang dibungkus

 

  1. Jaga Konsistensi Penamaan dan Struktur

Konsistensi adalah kunci dari API yang baik. Tetapkan standar dan patuhi itu.

  • Gaya Penamaan: Pilih camelCase (userId) atau snake_case (user_id) untuk key JSON Anda dan gunakan secara konsisten di semua endpoint. camelCase umum digunakan di dunia JavaScript.
  • Struktur URI: Gunakan huruf kecil semua dan pisahkan kata dengan tanda hubung (-) jika diperlukan (misalnya /product-categories).

 

  1. Sediakan Pesan Error yang Jelas

Ketika terjadi error, API yang baik tidak hanya mengembalikan kode status seperti 400 Bad Request, tetapi juga memberikan pesan yang jelas dalam format JSON.

Figure 3. Contoh respon error yang baik

 

  1. Lakukan Versioning pada API Anda

Kebutuhan bisnis berubah, begitu pula API Anda. Untuk menghindari breaking changes yang merusak aplikasi klien, lakukan versioning. Cara paling umum dan jelas adalah melalui URI.

  • https://api.example.com/v1/users
  • https://api.example.com/v2/users

Ini memungkinkan klien lama tetap berfungsi di v1 sementara klien baru dapat memanfaatkan fitur di v2.

 

  1. Dokumentasi adalah Kewajiban, Bukan Pilihan

API tanpa dokumentasi sama saja dengan tidak ada. Dokumentasi adalah panduan bagi developer lain. Gunakan tools seperti Swagger (OpenAPI Specification) untuk mendefinisikan dan secara otomatis menghasilkan dokumentasi interaktif.

Dokumentasi yang baik mencakup:

  • Deskripsi setiap endpoint.
  • HTTP verb yang digunakan.
  • Parameter yang dibutuhkan (di path, query, atau body).
  • Contoh request body.
  • Contoh respons untuk kasus sukses dan gagal.

 

 

Referensi: