API Design RESTful: Best Practices yang Wajib Diketahui Developer

API yang Buruk = Developer Experience yang Buruk

Saya sudah menggunakan ratusan API sepanjang karir saya. Dan yang paling saya ingat? Bukan yang paling canggih — tapi yang paling mudah dipakai. API design yang baik itu seperti jalan yang jelas: kamu tahu ke mana harus pergi tanpa perlu peta.

RESTful API Design Principles

1. Resource-Based URLs:

# Good: Resource-oriented
GET    /api/v1/users           # List users
GET    /api/v1/users/:id       # Get user
POST   /api/v1/users           # Create user
PUT    /api/v1/users/:id       # Update user
DELETE /api/v1/users/:id       # Delete user

# Bad: Action-oriented
GET    /api/v1/getUsers
POST   /api/v1/createUser
POST   /api/v1/deleteUser

2. Consistent Response Format:

// Success response
{
  "status": "success",
  "data": {
    "id": "usr_123",
    "email": "[email protected]",
    "name": "John Doe"
  }
}

// Error response
{
  "status": "error",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Email format is invalid"
  }
}

// Pagination
{
  "status": "success",
  "data": [...],
  "meta": {
    "total": 150,
    "page": 1,
    "per_page": 20,
    "total_pages": 8
  }
}

HTTP Methods dan Status Codes

// 2xx Success
200 OK           - GET, PUT successful
201 Created      - POST successful
204 No Content   - DELETE successful

// 4xx Client Error
400 Bad Request  - Validation error
401 Unauthorized - Not authenticated
403 Forbidden    - Authenticated but not authorized
404 Not Found    - Resource doesn't exist
409 Conflict     - Duplicate resource

// 5xx Server Error
500 Internal Server Error - Unexpected error
503 Service Unavailable   - Service temporarily down

Versioning Strategy

Saya selalu pakai URL versioning (/api/v1/) karena paling mudah dipahami dan di-cache. Rules yang saya ikuti:

Minor changes (adding new fields) tidak perlu version baru
Breaking changes (removing/renaming fields) wajib version baru
Deprecation notice minimal 6 bulan sebelum sunset

Documentation with OpenAPI

Setiap API yang saya buat harus punya OpenAPI (Swagger) documentation. Ini bukan optional. Developer harus bisa test API langsung dari documentation tanpa baca source code.

Kesimpulan

API design itu tentang empathy ke developer yang akan pakai API kamu. Buat konsisten, dokumentasi dengan jelas, dan selalu pertimbangkan backward compatibility.

Error Handling yang Konsisten

Satu aspek yang sering dilupakan adalah error handling yang konsisten. Setiap endpoint harus mengembalikan error dalam format yang sama. Saya biasanya membuat error response schema standar yang digunakan oleh seluruh API.

Yang juga penting: error messages harus actionable. Jangan hanya "Invalid request" — beri tahu user field mana yang salah dan kenapa. Ini memperbaiki developer experience secara signifikan. Saya pernah menerima feedback dari developer yang bilang: "API-nya bagus karena error message-nya jelas dan saya langsung tahu apa yang salah." Itu adalah pujian terbaik untuk API designer.