Format Respons API: Praktik Terbaik untuk API yang Konsisten
Respons API yang tidak konsisten adalah keluhan utama dari pengembang frontend. Ketika setiap endpoint mengembalikan data dalam bentuk yang berbeda, kode klien dipenuhi dengan kasus-kasus khusus. Format respons yang konsisten meningkatkan pengalaman pengembang, mengurangi bug, dan membuat API Anda terdokumentasi sendiri.
Envelope Respons
Bungkus setiap respons dalam struktur yang konsisten:
Sukses (Sumber Daya Tunggal)
{
"data": {
"id": "user_123",
"name": "Alice",
"email": "[email protected]",
"createdAt": "2024-01-15T10:30:00Z"
},
"meta": {
"requestId": "req_abc123"
}
}
Sukses (Koleksi)
{
"data": [
{ "id": "user_123", "name": "Alice" },
{ "id": "user_456", "name": "Bob" }
],
"meta": {
"total": 142,
"page": 1,
"perPage": 20,
"requestId": "req_def456"
}
}
Error
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Request validation failed",
"details": [
{ "field": "email", "message": "Invalid email format" }
]
},
"meta": {
"requestId": "req_ghi789"
}
}
Prinsip utamanya: klien selalu memeriksa data atau error di tingkat teratas. Jangan pernah mencampurkan data sukses dan informasi error dalam respons yang sama.
Validasi format respons Anda dengan JSON Validator kami.
Kode Status HTTP
Gunakan kode status dengan benar — kode status adalah hal pertama yang diperiksa klien:
Kode Sukses
| Kode | Kapan Digunakan |
|---|---|
| 200 OK | GET berhasil, PUT/PATCH berhasil |
| 201 Created | POST yang membuat sumber daya |
| 204 No Content | DELETE berhasil (tanpa body) |
Kode Error Klien
| Kode | Kapan Digunakan |
|---|---|
| 400 Bad Request | Sintaks permintaan tidak valid |
| 401 Unauthorized | Autentikasi tidak ada atau tidak valid |
| 403 Forbidden | Terautentikasi tetapi tidak diotorisasi |
| 404 Not Found | Sumber daya tidak ditemukan |
| 409 Conflict | Konflik status sumber daya (duplikat) |
| 422 Unprocessable | Sintaks valid tetapi ada kesalahan semantik |
| 429 Too Many Requests | Batas laju terlampaui |
Kode Error Server
| Kode | Kapan Digunakan |
|---|---|
| 500 Internal Server Error | Kegagalan server yang tidak terduga |
| 502 Bad Gateway | Kegagalan layanan upstream |
| 503 Service Unavailable | Kelebihan beban sementara atau pemeliharaan |
Desain Respons Error
Respons error yang baik membantu pengembang melakukan debug dengan cepat:
{
"error": {
"code": "RESOURCE_NOT_FOUND",
"message": "User with ID 'user_999' not found",
"details": [],
"documentationUrl": "https://api.example.com/docs/errors#RESOURCE_NOT_FOUND"
},
"meta": {
"requestId": "req_xyz789",
"timestamp": "2024-01-15T10:30:00Z"
}
}
Aturan:
codedapat dibaca mesin (string konstan, bukan status HTTP)messagedapat dibaca manusia (bisa berubah tanpa merusak klien)detailsmenyediakan error tingkat field untuk kegagalan validasirequestIdmemungkinkan tim dukungan melacak permintaan di log
Pola Paginasi
Berbasis Offset
Sederhana dan mendukung lompatan ke halaman sembarang:
{
"data": ["..."],
"meta": {
"page": 2,
"perPage": 20,
"total": 142,
"totalPages": 8
},
"links": {
"first": "/api/users?page=1&per_page=20",
"prev": "/api/users?page=1&per_page=20",
"next": "/api/users?page=3&per_page=20",
"last": "/api/users?page=8&per_page=20"
}
}
Berbasis Kursor
Lebih baik untuk data real-time dan dataset besar:
{
"data": ["..."],
"meta": {
"hasNext": true,
"hasPrev": true
},
"links": {
"next": "/api/users?cursor=eyJpZCI6MTQzfQ&limit=20",
"prev": "/api/users?cursor=eyJpZCI6MTIzfQ&limit=20&direction=prev"
}
}
Tanggal dan Waktu
Selalu gunakan ISO 8601 dengan informasi zona waktu:
{
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-15T14:22:33+00:00",
"expiresAt": "2024-12-31T23:59:59Z"
}
Jangan pernah menggunakan:
- Unix timestamp (ambigu: detik atau milidetik?)
- Tanggal lokal tanpa zona waktu
- Format kustom seperti MM/DD/YYYY
Untuk informasi lebih lanjut tentang penanganan timestamp, lihat panduan Unix Timestamps kami.
Null vs Field yang Tidak Ada
Dua pendekatan umum:
Sertakan dengan null (eksplisit):
{ "name": "Alice", "avatar": null, "bio": null }
Hapus field yang tidak ada (sparse):
{ "name": "Alice" }
Rekomendasi: Konsisten dalam API Anda. Null eksplisit lebih baik untuk bahasa bertipe (klien tahu field tersebut ada). Sparse lebih baik untuk lingkungan dengan keterbatasan bandwidth.
Versioning Respons
Ketika format respons berubah, beri versi pada API Anda:
GET /api/v2/users/123
Perubahan yang merusak yang memerlukan versioning:
- Menghapus field
- Mengubah tipe field
- Mengganti nama field
- Mengubah struktur envelope respons
Perubahan yang tidak merusak (aman tanpa versioning):
- Menambahkan field baru
- Menambahkan endpoint baru
- Menambahkan nilai enum baru
FAQ
Haruskah saya membungkus respons sukses dalam key data atau mengembalikan sumber daya secara langsung?
Menggunakan pembungkus data menyediakan struktur yang konsisten untuk semua respons dan menyisakan ruang untuk metadata, paginasi, dan tautan di samping data. Mengembalikan sumber daya secara langsung lebih sederhana untuk endpoint sumber daya tunggal. Sebagian besar API modern menggunakan pendekatan pembungkus untuk konsistensi.
Bagaimana cara menangani kegagalan parsial dalam operasi batch?
Kembalikan 200 dengan respons yang menyertakan keberhasilan dan kegagalan dalam objek data. Menggunakan 207 Multi-Status (WebDAV) adalah opsi lain tetapi kurang umum digunakan dalam REST API.
Penamaan Resource
Resource adalah kata benda, bukan kata kerja. Gunakan kata benda jamak untuk koleksi dan resource tunggal melalui ID:
GET /api/users # Daftar pengguna
POST /api/users # Buat pengguna
GET /api/users/123 # Ambil pengguna 123
PUT /api/users/123 # Perbarui pengguna 123
DELETE /api/users/123 # Hapus pengguna 123
Konvensi penamaan:
- Gunakan huruf kecil dengan tanda hubung:
/api/blog-posts(bukanblogPostsataublog_posts) - Sarangkan resource terkait:
/api/users/123/orders - Batasi penyarangan hingga 2 tingkat:
/api/users/123/orders/456(tidak lebih dalam) - Hindari kata kerja di URL:
/api/users/123/activatedapat diterima untuk aksi yang tidak dipetakan ke CRUD
Pemfilteran dan Pengurutan
Pemfilteran
GET /api/users?status=active&role=admin
GET /api/users?created_after=2024-01-01
GET /api/users?search=alice
Untuk filter kompleks, pertimbangkan parameter query khusus:
GET /api/users?filter[status]=active&filter[role]=admin
Pengurutan
GET /api/users?sort=name # Menaik
GET /api/users?sort=-created_at # Menurun (awali dengan -)
GET /api/users?sort=-created_at,name # Beberapa field
Pembatasan Rate
Komunikasikan batas rate di header respons:
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 67
X-RateLimit-Reset: 1705312800
Retry-After: 30
Kembalikan 429 Too Many Requests saat batas terlampaui, dengan pesan error yang jelas dan header Retry-After.
HATEOAS (Opsional tetapi Powerful)
Sertakan tautan ke resource dan aksi terkait:
{
"data": {
"id": "123",
"name": "Alice",
"links": {
"self": "/api/users/123",
"orders": "/api/users/123/orders",
"avatar": "/api/users/123/avatar"
}
}
}
Ini membuat API Anda self-documenting dan mengurangi konstruksi URL di sisi klien.
FAQ
Bagaimana seharusnya saya menangani pembaruan parsial (PATCH vs PUT)?
Gunakan PUT untuk penggantian resource lengkap (klien mengirim semua field). Gunakan PATCH untuk pembaruan parsial (klien mengirim hanya field yang berubah). PATCH dengan JSON Merge Patch (RFC 7396) adalah pendekatan paling sederhana: kirim objek JSON dengan hanya field yang akan diperbarui, dan null untuk menghapus field.
Berbasis Keyset
GET /api/users?after_id=123&limit=20
Menggunakan ID item terakhir (atau field terurut lainnya) untuk mengambil halaman berikutnya. Mirip dengan berbasis cursor tetapi dengan parameter yang transparan.
Rekomendasi: Gunakan berbasis cursor untuk feed real-time dan dataset besar. Gunakan berbasis offset untuk dashboard admin di mana perpindahan halaman penting.
Berbasis Header
GET /api/users
Accept: application/vnd.myapi.v2+json
Kelebihan: URL bersih. Kekurangan: Lebih sulit diuji, kurang mudah ditemukan.
Parameter Query
GET /api/users?version=2
Kelebihan: Mudah diuji. Kekurangan: Semantik parameter opsional.
Rekomendasi: Versioning path URL adalah pilihan paling praktis. Eksplisit, dapat di-cache, dan berfungsi dengan setiap alat HTTP.
Haruskah saya menggunakan spesifikasi JSON:API atau merancang format sendiri?
Spesifikasi JSON:API (jsonapi.org) menyediakan standar yang komprehensif, tetapi bisa verbose untuk API sederhana. Untuk sebagian besar proyek, merancang format kustom yang lebih sederhana mengikuti pola-pola dalam panduan ini lebih praktis. Gunakan JSON:API jika Anda membutuhkan library klien otomatis dan standar yang ketat.
Sumber Terkait
- JSON Formatter — Format respons API
- Validasi JSON Schema — Validasi struktur respons
🛠️ Coba sekarang: JSON Formatter | JSON Validator — 100% gratis, semua diproses di browser Anda. Tidak ada data yang diunggah.