~/codeearth

Pemrograman & AI

Desain REST API yang Rapi: Penamaan Endpoint, Status Code, Error, dan Versi

Panduan praktis merancang REST API yang konsisten dan mudah dipakai tim lain: penamaan resource, metode HTTP, status code, format error, pagination, versioning, autentikasi, dan dokumentasi.

AArdi27 September 2026 3 menit baca

API yang dirancang asal jadi mungkin berjalan hari ini, tetapi menyulitkan semua orang yang memakainya nanti: programmer frontend, tim mobile, vendor yang mengintegrasikan sistemnya, bahkan diri Anda sendiri enam bulan lagi. Beberapa aturan sederhana membuat API jauh lebih mudah dipahami dan dirawat.

Gunakan kata benda untuk resource

Endpoint mewakili resource (benda), sedangkan aksinya ditentukan oleh metode HTTP:

MetodeEndpointArti
GET/pasienDaftar pasien
GET/pasien/{id}Detail satu pasien
POST/pasienMenambah pasien baru
PATCH/pasien/{id}Mengubah sebagian data pasien
GET/pasien/{id}/kunjunganDaftar kunjungan milik pasien tersebut

Hindari endpoint seperti /getPasien, /tambahPasienBaru, atau /hapus_pasien. Pilih satu gaya penulisan (misalnya huruf kecil dengan tanda hubung) dan gunakan secara konsisten di seluruh API.

Status code yang tepat

KodeKapan dipakai
200 OKPermintaan berhasil dan ada data yang dikembalikan
201 CreatedData baru berhasil dibuat
204 No ContentBerhasil tanpa isi balasan, misalnya setelah membatalkan data
400 Bad RequestFormat permintaan salah
401 UnauthorizedBelum login atau token tidak valid
403 ForbiddenSudah login tetapi tidak berhak mengakses data ini
404 Not FoundData tidak ditemukan
409 ConflictBentrok dengan data yang ada, misalnya NIK sudah terdaftar
422 Unprocessable EntityValidasi gagal, misalnya tanggal lahir di masa depan
500 Internal Server ErrorKesalahan di sisi server

Jangan mengembalikan 200 untuk semua kondisi lalu menaruh status sebenarnya di dalam isi balasan. Klien, alat monitoring, dan cache mengandalkan status code.

Format error yang konsisten

Gunakan satu bentuk error untuk semua endpoint, sehingga aplikasi pemakai cukup menangani satu format:

{
  "error": {
    "kode": "VALIDASI_GAGAL",
    "pesan": "Data pasien tidak valid.",
    "detail": [
      { "field": "tanggal_lahir", "pesan": "Tanggal lahir tidak boleh di masa depan." }
    ]
  }
}

Pesan error untuk pengguna harus jelas tetapi tidak membocorkan detail internal seperti query SQL, jalur file, atau stack trace. Detail teknis cukup dicatat di log server.

Pagination, filter, dan urutan

Jangan pernah mengembalikan seluruh isi tabel dalam satu permintaan. Contoh pola yang umum:

GET /kunjungan?tanggal=2026-09-24&poli=umum&halaman=2&per_halaman=50&urut=-waktu_datang

Sertakan informasi halaman di balasan, misalnya total data dan jumlah halaman, agar tampilan bisa membuat navigasi yang benar. Batasi nilai maksimal per_halaman untuk melindungi server.

Contoh balasan yang berhasil

Balasan daftar data sebaiknya juga punya bentuk yang konsisten, misalnya data di satu tempat dan informasi halaman di tempat lain:

{
  "data": [
    { "id": 1021, "no_rm": "RM001234", "nama": "Contoh Pasien", "tanggal_lahir": "1990-05-12" }
  ],
  "meta": { "halaman": 2, "per_halaman": 50, "total": 1340 }
}

Gunakan format tanggal ISO 8601 (misalnya 2026-09-24T10:30:00+07:00) dan nama field yang konsisten di semua endpoint.

Versi API

Begitu API dipakai pihak lain, perubahan yang merusak kompatibilitas harus dihindari. Cantumkan versi, misalnya /api/v1/pasien. Menambah field baru biasanya aman. Menghapus atau mengganti nama field, atau mengubah arti data, sebaiknya dilakukan di versi baru, dengan masa transisi yang diumumkan.

Keamanan dasar

  • Selalu gunakan HTTPS.
  • Gunakan token dengan masa berlaku, bukan password yang dikirim di setiap permintaan.
  • Periksa hak akses pada setiap data, bukan hanya pada endpoint. Pengguna yang boleh membuka /pasien/{id} belum tentu boleh membuka semua ID. Celah ini dikenal sebagai IDOR.
  • Batasi jumlah permintaan (rate limit) untuk mencegah penyalahgunaan.
  • Jangan mengembalikan field yang tidak dibutuhkan, terutama data sensitif. Lihat keamanan data pasien dan UU PDP.

Dokumentasi

API tanpa dokumentasi memaksa setiap pemakainya bertanya atau membaca kode. Standar seperti OpenAPI memungkinkan dokumentasi yang bisa dibaca manusia sekaligus dipakai untuk membuat contoh permintaan dan pengujian otomatis. Sertakan contoh permintaan dan balasan untuk setiap endpoint, termasuk contoh error.

Pertanyaan yang sering diajukan

REST atau GraphQL? Untuk aplikasi bisnis dan integrasi antarsistem, REST lebih umum dan lebih mudah dipahami vendor lain. GraphQL berguna bila tampilan membutuhkan kombinasi data yang sangat bervariasi. Pilih yang paling mudah dirawat oleh tim Anda.

Perlukah idempotency untuk POST? Untuk transaksi penting seperti pembayaran atau pendaftaran, pertimbangkan kunci idempotensi yang dikirim klien. Bila jaringan putus dan permintaan dikirim ulang, server tidak membuat transaksi ganda.

Bagaimana menguji API? Tulis test otomatis untuk endpoint penting, termasuk kasus gagal seperti token salah dan data tidak valid. Lihat jenis pengujian dan cara menulis test case.

Baca juga