Kode Status HTTP Mana yang Seharusnya Digunakan REST API?

TL;DR

API REST harus menggunakan kode status HTTP dengan benar: 200 untuk GET yang berhasil, 201 untuk POST yang berhasil dengan pembuatan sumber daya, 204 untuk DELETE yang berhasil, 400 untuk kesalahan klien, 401 untuk kegagalan otentikasi, 404 untuk tidak ditemukan, dan 500 untuk kesalahan server. Modern PetstoreAPI mengimplementasikan semua kode status HTTP standar dengan semantik yang tepat dan respons kesalahan RFC 9457.

Pendahuluan

API Anda mengembalikan 200 OK untuk semuanya. Berhasil? 200 OK. Kesalahan validasi? 200 OK dengan pesan kesalahan di badan respons. Sumber daya tidak ditemukan? 200 OK dengan {"error": "not found"}. Kegagalan otentikasi? Anda menebaknya—200 OK.

Ini salah. Kode status HTTP ada karena suatu alasan. Kode-kode ini memberi tahu klien apa yang terjadi tanpa mengurai badan respons. Cache, proksi, dan alat pemantauan mengandalkan kode status. Ketika Anda mengembalikan 200 untuk kesalahan, Anda merusak seluruh ekosistem HTTP.

Swagger Petstore yang lama melakukan kesalahan kode status: mengembalikan 200 untuk permintaan POST yang seharusnya mengembalikan 201, menggunakan 200 untuk operasi DELETE yang seharusnya mengembalikan 204, dan melewatkan kode kesalahan penting. Modern PetstoreAPI memperbaikinya dengan mengimplementasikan semantik HTTP yang tepat di semua endpoint.

💡

Jika Anda sedang membangun atau menguji API REST, Apidog membantu Anda memvalidasi penggunaan kode status, menguji skenario kesalahan, dan memastikan API Anda mengikuti standar HTTP. Anda dapat menentukan kode status yang diharapkan, menjalankan pengujian otomatis, dan menangkap respons yang salah sebelum deployment.

button

Dalam panduan ini, Anda akan mempelajari kode status HTTP mana yang penting untuk API REST, kapan harus menggunakan masing-masing, dan bagaimana Modern PetstoreAPI mengimplementasikannya dengan benar.

Masalah Kode Status

Banyak API menganggap kode status sebagai hal yang belakangan. Hasilnya: semantik HTTP yang rusak dan klien yang bingung.

Anti-Pola “200 OK untuk Segalanya”

// Success
GET /users/123
200 OK
{"id": 123, "name": "John"}

// Error (but still 200!)
GET /users/999
200 OK
{"error": "User not found"}

// Validation error (still 200!)
POST /users
200 OK
{"error": "Email is required"}

Masalah:

Klien tidak dapat membedakan keberhasilan dari kegagalan tanpa mengurai badan respons
Cache HTTP meng-cache respons kesalahan
Alat pemantauan melaporkan positif palsu
Logika coba lagi tidak berfungsi dengan benar

Mengapa Ini Terjadi

Pengembang mengembalikan 200 karena:

Mereka tidak tahu kode status lainnya
Mereka berpikir kode status bersifat opsional
Mereka ingin menghindari “merusak” klien
Mereka menyalin contoh yang buruk (seperti Swagger Petstore lama)

Kode Status HTTP Esensial untuk API REST

Anda tidak memerlukan semua 60+ kode status HTTP. Fokus pada yang penting ini.

Referensi Cepat

Berhasil (2xx):

200 OK - GET, PUT, PATCH yang berhasil
201 Created - POST yang berhasil dengan pembuatan sumber daya
204 No Content - DELETE, PUT yang berhasil tanpa badan respons

Kesalahan Klien (4xx):

400 Bad Request - Format permintaan tidak valid atau kesalahan validasi
401 Unauthorized - Otentikasi hilang atau tidak valid
403 Forbidden - Sudah terotentikasi tetapi tidak diotorisasi
404 Not Found - Sumber daya tidak ada
409 Conflict - Konflik sumber daya (duplikat, ketidakcocokan versi)
422 Unprocessable Entity - Format valid tetapi kesalahan semantik
429 Too Many Requests - Batas kecepatan terlampaui

Kesalahan Server (5xx):

500 Internal Server Error - Kesalahan server yang tidak terduga
502 Bad Gateway - Kesalahan layanan upstream
503 Service Unavailable - Ketidaktersediaan sementara
504 Gateway Timeout - Waktu habis upstream

Kode Keberhasilan (2xx)

Kode keberhasilan menunjukkan permintaan berhasil. Kode yang berbeda menyampaikan arti yang berbeda.

200 OK

Gunakan untuk: Permintaan GET, PUT, PATCH yang berhasil yang mengembalikan data.

GET /pets/123
200 OK
{
  "id": "019b4132-70aa-764f-b315-e2803d882a24",
  "name": "Fluffy",
  "species": "CAT"
}

Jangan gunakan untuk: Permintaan POST yang membuat sumber daya (gunakan 201), permintaan DELETE (gunakan 204).

201 Created

Gunakan untuk: Permintaan POST yang berhasil yang membuat sumber daya baru.

POST /pets
201 Created
Location: https://petstoreapi.com/pets/019b4132-70aa-764f-b315-e2803d882a24
{
  "id": "019b4132-70aa-764f-b315-e2803d882a24",
  "name": "Fluffy",
  "species": "CAT"
}

Poin-poin penting:

Sertakan header Location dengan URL sumber daya baru
Kembalikan sumber daya yang dibuat di badan respons
Klien tahu sumber daya dibuat, bukan hanya diperbarui

Modern PetstoreAPI mengembalikan 201 untuk semua operasi POST yang membuat sumber daya.

204 No Content

Gunakan untuk: Permintaan DELETE, PUT, atau PATCH yang berhasil tanpa badan respons.

DELETE /pets/019b4132-70aa-764f-b315-e2803d882a24
204 No Content

Poin-poin penting:

Tidak ada badan respons (menghemat bandwidth)
Menunjukkan keberhasilan
Umum untuk operasi DELETE

Kode Kesalahan Klien (4xx)

Kode kesalahan klien menunjukkan bahwa klien membuat kesalahan. Permintaan tidak boleh dicoba lagi tanpa modifikasi.

400 Bad Request

Gunakan untuk: Permintaan yang salah format, JSON tidak valid, bidang yang wajib diisi hilang.

POST /pets
400 Bad Request
Content-Type: application/problem+json

{
  "type": "https://petstoreapi.com/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Request validation failed",
  "invalid-params": [
    {
      "name": "name",
      "reason": "Name is required"
    }
  ]
}

Modern PetstoreAPI menggunakan format RFC 9457 untuk semua respons kesalahan.

401 Unauthorized

Gunakan untuk: Kredensial otentikasi hilang atau tidak valid.

GET /pets
401 Unauthorized
WWW-Authenticate: Bearer realm="PetstoreAPI"

{
  "type": "https://petstoreapi.com/errors/authentication-required",
  "title": "Authentication Required",
  "status": 401,
  "detail": "Valid authentication credentials required"
}

Poin-poin penting:

Sertakan header WWW-Authenticate
Klien harus meminta kredensial atau token refresh
Jangan bingung dengan 403 (otorisasi)

403 Forbidden

Gunakan untuk: Pengguna yang terotentikasi tidak memiliki izin.

DELETE /pets/019b4132-70aa-764f-b315-e2803d882a24
403 Forbidden

{
  "type": "https://petstoreapi.com/errors/insufficient-permissions",
  "title": "Insufficient Permissions",
  "status": 403,
  "detail": "You don't have permission to delete this pet"
}

Perbedaan dari 401:

401: “Siapa Anda?” (otentikasi)
403: “Saya tahu siapa Anda, tetapi Anda tidak bisa melakukan itu” (otorisasi)

404 Not Found

Gunakan untuk: Sumber daya tidak ada.

GET /pets/nonexistent-id
404 Not Found

{
  "type": "https://petstoreapi.com/errors/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "Pet not found"
}

Jangan gunakan untuk: Kegagalan otorisasi (gunakan 403), kesalahan validasi (gunakan 400).

409 Conflict

Gunakan untuk: Konflik sumber daya seperti duplikat atau ketidakcocokan versi.

POST /pets
409 Conflict

{
  "type": "https://petstoreapi.com/errors/duplicate-resource",
  "title": "Duplicate Resource",
  "status": 409,
  "detail": "A pet with this microchip ID already exists"
}

422 Unprocessable Entity

Gunakan untuk: Format permintaan valid tetapi kesalahan semantik.

POST /pets
422 Unprocessable Entity

{
  "type": "https://petstoreapi.com/errors/business-rule-violation",
  "title": "Business Rule Violation",
  "status": 422,
  "detail": "Cannot adopt more than 5 pets per household"
}

Perbedaan dari 400:

400: Permintaan yang salah format (JSON tidak valid, tipe salah)
422: Permintaan yang terformat dengan baik tetapi melanggar aturan bisnis

429 Too Many Requests

Gunakan untuk: Batas kecepatan terlampaui.

GET /pets
429 Too Many Requests
RateLimit-Limit: 100
RateLimit-Remaining: 0
RateLimit-Reset: 1678886400

{
  "type": "https://petstoreapi.com/errors/rate-limit-exceeded",
  "title": "Rate Limit Exceeded",
  "status": 429,
  "detail": "Rate limit of 100 requests per hour exceeded"
}

Modern PetstoreAPI menggunakan header batas kecepatan IETF.

Kode Kesalahan Server (5xx)

Kode kesalahan server menunjukkan bahwa server gagal. Klien dapat mencoba lagi permintaan ini.

500 Internal Server Error

Gunakan untuk: Kesalahan server yang tidak terduga.

GET /pets
500 Internal Server Error

{
  "type": "https://petstoreapi.com/errors/internal-error",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "An unexpected error occurred"
}

Jangan sertakan: Jejak tumpukan, detail internal, kesalahan database dalam produksi.

503 Service Unavailable

Gunakan untuk: Ketidaktersediaan sementara (pemeliharaan, kelebihan beban).

GET /pets
503 Service Unavailable
Retry-After: 3600

{
  "type": "https://petstoreapi.com/errors/service-unavailable",
  "title": "Service Unavailable",
  "status": 503,
  "detail": "Service temporarily unavailable for maintenance"
}

Sertakan header Retry-After untuk memberi tahu klien kapan harus mencoba lagi.

Bagaimana Modern PetstoreAPI Menggunakan Kode Status

Modern PetstoreAPI mengimplementasikan semantik HTTP yang tepat di semua endpoint.

Contoh: Manajemen Hewan Peliharaan

// Daftar hewan peliharaan
GET /pets
200 OK

// Buat hewan peliharaan
POST /pets
201 Created
Location: https://petstoreapi.com/pets/{id}

// Dapatkan hewan peliharaan
GET /pets/{id}
200 OK (ditemukan) or 404 Not Found

// Perbarui hewan peliharaan
PUT /pets/{id}
200 OK (dengan badan respons) or 204 No Content

// Hapus hewan peliharaan
DELETE /pets/{id}
204 No Content (berhasil) or 404 Not Found

Respons Kesalahan

Semua kesalahan menggunakan format RFC 9457:

{
  "type": "https://petstoreapi.com/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Request validation failed",
  "instance": "/pets",
  "invalid-params": [
    {
      "name": "name",
      "reason": "Name must be between 1 and 100 characters"
    }
  ]
}

Lihat dokumentasi penanganan kesalahan Modern PetstoreAPI untuk contoh lengkap.

Menguji Kode Status dengan Apidog

Apidog membantu Anda menguji perilaku kode status di semua skenario.

Definisikan Kode Status yang Diharapkan

paths:
  /pets:
    post:
      responses:
        '201':
          description: Hewan peliharaan dibuat
        '400':
          description: Kesalahan validasi
        '401':
          description: Otentikasi diperlukan
        '429':
          description: Batas kecepatan terlampaui

Uji Semua Skenario

Buat kasus uji untuk:

Skenario keberhasilan (200, 201, 204)
Kesalahan validasi (400, 422)
Otentikasi/otorisasi (401, 403)
Tidak ditemukan (404)
Pembatasan kecepatan (429)
Kesalahan server (500, 503)

Pengujian Otomatis

// Skrip uji Apidog
pm.test("Returns 201 for successful creation", () => {
  pm.response.to.have.status(201);
  pm.response.to.have.header("Location");
});

pm.test("Returns 400 for missing required fields", () => {
  pm.response.to.have.status(400);
  pm.expect(pm.response.json().type).to.include("validation-error");
});

Kesalahan Umum yang Harus Dihindari

Kesalahan 1: Menggunakan 200 untuk POST

// Salah
POST /pets
200 OK

// Benar
POST /pets
201 Created
Location: https://petstoreapi.com/pets/{id}

Kesalahan 2: Menggunakan 200 untuk DELETE

// Salah
DELETE /pets/{id}
200 OK
{"message": "Berhasil dihapus"}

// Benar
DELETE /pets/{id}
204 No Content

Kesalahan 3: Membingungkan 401 dan 403

// Salah: Pengguna terotentikasi tetapi tidak memiliki izin
401 Unauthorized

// Benar
403 Forbidden

Kesalahan 4: Menggunakan 500 untuk Kesalahan Klien

// Salah: Kesalahan validasi mengembalikan 500
POST /pets
500 Internal Server Error

// Benar
POST /pets
400 Bad Request

Kesimpulan

Kode status HTTP bukanlah pilihan. Kode-kode ini adalah bagian dari spesifikasi HTTP dan esensial untuk membangun API REST yang tepat.

Gunakan kode status yang benar:

200 untuk pembacaan yang berhasil
201 untuk pembuatan yang berhasil
204 untuk penghapusan yang berhasil
400 untuk kesalahan klien
401 untuk otentikasi
404 untuk tidak ditemukan
500 untuk kesalahan server

Modern PetstoreAPI menunjukkan penggunaan kode status yang benar di semua endpoint. Pelajari dokumentasi API REST untuk melihat implementasi yang tepat.

Uji kode status Anda dengan Apidog untuk memastikan API Anda mengikuti standar HTTP.

FAQ

Haruskah saya menggunakan 200 atau 204 untuk DELETE yang berhasil?

Gunakan 204 No Content. Ini menunjukkan keberhasilan tanpa badan respons, menghemat bandwidth. Gunakan 200 hanya jika Anda perlu mengembalikan informasi tentang sumber daya yang dihapus.

Apa perbedaan antara 400 dan 422?

400 berarti permintaan salah format (JSON tidak valid, tipe salah). 422 berarti permintaan terformat dengan baik tetapi melanggar aturan bisnis.

Kapan saya harus menggunakan 401 vs 403?

401 berarti “otentikasi diri Anda” (kredensial hilang atau tidak valid). 403 berarti “Anda terotentikasi tetapi tidak diotorisasi” (izin tidak cukup).

Haruskah saya mengembalikan 404 atau 403 untuk sumber daya yang tidak dapat diakses pengguna?

Kembalikan 403 jika sumber daya ada tetapi pengguna tidak memiliki izin. Kembalikan 404 jika Anda ingin menyembunyikan keberadaan sumber daya dari pengguna yang tidak berwenang.

Bagaimana cara menguji semua skenario kode status?

Gunakan Apidog untuk membuat kasus uji untuk keberhasilan, kesalahan validasi, kegagalan otentikasi, tidak ditemukan, dan kesalahan server. Jalankan pengujian otomatis di CI/CD.

Kode status apa untuk pembatasan kecepatan?

Gunakan 429 Too Many Requests dengan header RateLimit-*. Sertakan Retry-After untuk memberi tahu klien kapan mereka dapat mencoba lagi.

Haruskah saya menggunakan 500 untuk semua kesalahan server?

Gunakan 500 untuk kesalahan yang tidak terduga. Gunakan 502 untuk kegagalan layanan upstream, 503 untuk ketidaktersediaan sementara, dan 504 untuk waktu habis.

Bagaimana Modern PetstoreAPI menangani kesalahan?

Semua kesalahan menggunakan format RFC 9457 dengan kode status yang tepat. Lihat dokumentasi penanganan kesalahan untuk contoh.