Membuat REST API - Panduan Ringkas

Pendahuluan

REST API adalah jembatan komunikasi antar aplikasi menggunakan protokol HTTP. Dengan API yang rapi, frontend, mobile app, dan layanan pihak ketiga bisa terhubung dengan data yang sama secara konsisten.

1. Prinsip Dasar REST yang Wajib Dipahami

• Resource-based: URL mewakili resource, misalnya /api/users.
• HTTP Methods: gunakan method sesuai aksi: GET, POST, PUT/PATCH, DELETE.
• Stateless: setiap request membawa konteks sendiri (token, parameter, payload).
• Representasi Data: umumnya JSON agar mudah diproses berbagai platform.

2. Desain Endpoint yang Benar

Gunakan pola URL yang konsisten dan mudah dipahami.

GET    /api/articles
GET    /api/articles/{id}
POST   /api/articles
PUT    /api/articles/{id}
DELETE /api/articles/{id}

Hindari URL berbasis aksi seperti /getArticles atau /deleteArticle. Gunakan noun (resource), bukan verb.

3. Struktur Response JSON Standar

Tetapkan format response sejak awal agar frontend tidak bingung.

{
  "success": true,
  "message": "Data berhasil diambil",
  "data": [...],
  "meta": {
    "page": 1,
    "per_page": 10,
    "total": 120
  }
}

4. HTTP Status Code yang Tepat

• 200 OK: request berhasil.
• 201 Created: data baru berhasil dibuat.
• 400 Bad Request: payload tidak valid.
• 401 Unauthorized: belum login/token tidak valid.
• 403 Forbidden: tidak punya izin.
• 404 Not Found: resource tidak ditemukan.
• 422 Unprocessable Entity: validasi gagal.
• 500 Internal Server Error: error server.

5. Validasi Request

Semua input dari client harus divalidasi sebelum diproses dan disimpan.

$request->validate([
  'title' => 'required|string|max:255',
  'content' => 'required|string',
  'status' => 'required|in:draft,published'
]);

6. Authentication dan Authorization

Gunakan token-based authentication (misal Sanctum/JWT) untuk endpoint privat. Pisahkan kontrol akses per role agar user hanya bisa mengakses data yang berhak mereka lihat.

• Admin: kelola semua data.
• Editor: kelola konten tertentu.
• User: akses data miliknya sendiri.

7. Pagination, Filter, dan Sorting

Untuk data list, selalu sediakan pagination agar performa stabil.

GET /api/articles?page=1&per_page=10&sort=created_at:desc&status=published

Tambahkan filter seperti kategori, status, keyword pencarian, dan rentang tanggal.

8. Error Handling yang Konsisten

Jangan kirim error mentah dari server ke client. Bungkus dalam format JSON standar.

{
  "success": false,
  "message": "Validasi gagal",
  "errors": {
    "title": ["Kolom title wajib diisi"]
  }
}

9. Versioning API

Gunakan versi di URL untuk menjaga kompatibilitas saat ada perubahan besar.

/api/v1/articles
/api/v2/articles

Dengan versioning, aplikasi lama tetap jalan saat API baru dirilis.

10. Dokumentasi API

Minimal dokumentasikan endpoint, method, header, payload, response, dan contoh error. Jika memungkinkan gunakan OpenAPI/Swagger agar tim frontend dan integrator lebih cepat implementasi.

Checklist Singkat Sebelum Go-Live

• Endpoint konsisten dan mengikuti REST.
• Validasi input lengkap.
• Status code benar.
• Auth + permission aman.
• Rate limit aktif.
• Logging dan monitoring berjalan.
• Dokumentasi siap dipakai tim lain.

Penutup

Membangun REST API yang baik bukan cuma soal endpoint berjalan, tapi soal konsistensi, keamanan, dan kemudahan maintenance jangka panjang. Mulai dari struktur sederhana, lalu tingkatkan dengan validasi, auth, pagination, dan dokumentasi yang rapi.