Blog

Mengapa Contoh Swagger Petstore Desain REST API yang Buruk?

Ashley Innocent

Ashley Innocent

13 March 2026

Mengapa Contoh Swagger Petstore Desain REST API yang Buruk?

Apidog untuk Perusahaan

Penerapan On-Premises

SSO & RBAC

Sesuai SOC 2

Jelajahi Apidog Enterprise

Intinya

Swagger Petstore melanggar prinsip dasar REST: ia menggunakan nama sumber daya tunggal secara tidak konsisten, menyertakan kata kerja tindakan dalam URL, mengembalikan kode status HTTP yang salah, mengekspos kata sandi dalam permintaan GET, dan mengembalikan array kosong tanpa metadata. Modern PetstoreAPI memperbaiki semua masalah ini dengan desain RESTful yang tepat, penanganan kesalahan RFC 9457, dan pola siap produksi.

Pendahuluan

Selama lebih dari satu dekade, Swagger Petstore telah menjadi contoh standar untuk mempelajari OpenAPI. Jutaan pengembang telah mempelajarinya, menyalin polanya, dan membangun API produksi berdasarkan desainnya. Ada satu masalah: itu mengajari Anda membangun API yang buruk.

Swagger Petstore melanggar prinsip dasar REST, menyertakan kerentanan keamanan, dan menunjukkan anti-pola yang merugikan sistem produksi. Ini seperti belajar mengemudi dengan mobil yang pedal rem dan gasnya tertukar—Anda akan belajar, tetapi Anda akan belajar dengan salah.

Kerusakannya nyata. Pengembang yang belajar dari Swagger Petstore membawa anti-pola ini ke kode produksi. API dibangun dengan penamaan yang tidak konsisten, metode HTTP yang salah, dan celah keamanan. Tinjauan kode melewatkan masalah ini karena "begitulah cara Petstore melakukannya."

💡
Jika Anda membangun atau menguji API REST, Apidog membantu Anda memvalidasi desain API terhadap prinsip REST, menguji perilaku endpoint, dan menangkap kesalahan desain sebelum mencapai produksi. Anda dapat mengimpor spesifikasi OpenAPI, menjalankan pengujian otomatis, dan memastikan API Anda mengikuti konvensi REST yang tepat.
tombol

Dalam panduan ini, Anda akan belajar persis apa yang salah dengan Swagger Petstore, mengapa masalah ini penting, dan bagaimana Modern PetstoreAPI memperbaikinya dengan pola siap produksi. Anda akan melihat perbandingan berdampingan, memahami dampak setiap pelanggaran, dan menemukan cara menguji API Anda dengan benar menggunakan Apidog.

Masalah Warisan Swagger Petstore

Swagger Petstore dibuat pada tahun 2011 sebagai contoh sederhana untuk spesifikasi Swagger (sekarang OpenAPI). Ia memenuhi tujuannya: menunjukkan cara menulis spesifikasi OpenAPI. Namun, ia tidak pernah dimaksudkan sebagai referensi untuk desain API REST.

Mengapa Ini Menjadi Standar De Facto

Ketika pengembang mempelajari OpenAPI, mereka memulai dengan contoh resmi. Swagger Petstore adalah contoh itu. Ini ada dalam dokumentasi, tutorial, dan generator kode. Jika Anda pernah menggunakan Swagger UI atau Swagger Codegen, Anda pasti pernah melihatnya.

Masalahnya: pengembang mengasumsikan "contoh resmi = praktik terbaik." Mereka menyalin polanya tanpa mempertanyakannya. Kursus desain API menggunakannya sebagai alat pengajaran. Perusahaan membangun API internal mengikuti strukturnya.

Biaya Contoh yang Buruk

Contoh yang buruk bertambah seiring waktu:

  1. Pengembang junior mempelajari anti-pola - Mereka tidak tahu ini adalah kesalahan
  2. Generator kode melanggengkan masalah - SDK yang dihasilkan mewarisi cacat
  3. Alat dokumentasi menampilkan contoh yang buruk - Swagger UI menampilkan Petstore secara default
  4. Perusahaan membangun API produksi dengan cara ini - "Jika cukup baik untuk Swagger..."

Swagger Petstore kemungkinan telah memengaruhi lebih banyak desain API daripada contoh lain dalam sejarah. Itulah mengapa kekurangannya penting.

Pelanggaran REST Kritis di Swagger Petstore

Mari kita periksa pelanggaran REST spesifik di Swagger Petstore dan mengapa itu salah.

1. Penamaan Sumber Daya yang Tidak Konsisten (Jamak vs Tunggal)

Pelanggaran:

GET /pet/{petId}           ← Singular
GET /store/inventory       ← Plural
POST /pet                  ← Singular
GET /user/{username}       ← Singular

Mengapa Ini Salah:

Sumber daya REST merepresentasikan koleksi. Sebuah koleksi bersifat jamak. Saat Anda mengakses /pets, Anda mengakses koleksi hewan peliharaan. Saat Anda mengakses /pets/123, Anda mengakses item 123 dalam koleksi hewan peliharaan.

Mencampur tunggal dan jamak merusak model mental ini. Apakah /pet/123 mengakses koleksi hewan peliharaan atau sumber daya hewan peliharaan tunggal? Inkonsistensi ini menimbulkan kebingungan.

Perbaikan Modern PetstoreAPI:

GET /pets/{petId}          ← Always plural
GET /stores/inventory      ← Consistent
POST /pets                 ← Plural for collection
GET /users/{username}      ← Plural everywhere

Modern PetstoreAPI menggunakan nama sumber daya jamak secara konsisten di semua endpoint. Periksa dokumentasi API REST untuk struktur endpoint yang lengkap.

2. Kata Kerja Tindakan di URL

Pelanggaran:

GET /pet/findByStatus?status=available
GET /pet/findByTags?tags=tag1,tag2
GET /user/login?username=john&password=secret
GET /user/logout

Mengapa Ini Salah:

URL REST harus merepresentasikan sumber daya (kata benda), bukan tindakan (kata kerja). Metode HTTP adalah kata kerjanya. GET /pets berarti "dapatkan sumber daya hewan peliharaan." Menambahkan findByStatus adalah berlebihan—itulah gunanya parameter kueri.

Kata kerja tindakan di URL menunjukkan bahwa Anda berpikir dalam istilah RPC (Remote Procedure Call), bukan istilah REST. Anda mengekspos detail implementasi, bukan sumber daya.

Perbaikan Modern PetstoreAPI:

GET /pets?status=AVAILABLE              ← Resource + filter
GET /pets?tags=tag1,tag2                ← Query parameters for filtering
POST /auth/login                        ← Separate auth resource
POST /auth/logout                       ← RESTful auth endpoints

Modern PetstoreAPI menggunakan parameter kueri untuk pemfilteran dan sumber daya autentikasi terpisah. Lihat panduan autentikasi untuk pola autentikasi yang tepat.

3. Kode Status HTTP yang Salah

Pelanggaran:

POST /pet
Response: 200 OK          ← Should be 201 Created

DELETE /pet/{petId}
Response: 200 OK          ← Should be 204 No Content
{
  "message": "Pet deleted"
}

Mengapa Ini Salah:

Kode status HTTP memiliki makna spesifik:

Menggunakan 200 untuk semuanya merusak semantik HTTP. Klien tidak dapat membedakan antara "sumber daya diambil" dan "sumber daya dibuat." Mengembalikan body dengan DELETE membuang bandwidth—klien tidak memerlukan teks konfirmasi.

Perbaikan Modern PetstoreAPI:

POST /pets
Response: 201 Created
Location: /pets/019b4132-70aa-764f-b315-e2803d882a24
{
  "id": "019b4132-70aa-764f-b315-e2803d882a24",
  "name": "Fluffy",
  "status": "AVAILABLE"
}

DELETE /pets/{petId}
Response: 204 No Content
(no body)

Modern PetstoreAPI menggunakan kode status HTTP yang benar dan menyertakan header Location untuk sumber daya yang dibuat. Periksa panduan kode status HTTP untuk pemetaan lengkap.

4. Array Kosong Tanpa Metadata

Pelanggaran:

GET /pet/findByStatus?status=available
Response: 200 OK
[
  {"id": 1, "name": "Fluffy"},
  {"id": 2, "name": "Buddy"}
]

Mengapa Ini Salah:

Mengembalikan array kosong menimbulkan masalah:

Perbaikan Modern PetstoreAPI:

GET /pets?status=AVAILABLE
Response: 200 OK
{
  "data": [
    {"id": "019b4132-70aa-764f-b315-e2803d882a24", "name": "Fluffy"},
    {"id": "019b4127-54d5-76d9-b626-0d4c7bfce5b6", "name": "Buddy"}
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "totalItems": 45,
    "totalPages": 3
  },
  "links": {
    "self": "/pets?status=AVAILABLE&page=1",
    "next": "/pets?status=AVAILABLE&page=2",
    "last": "/pets?status=AVAILABLE&page=3"
  }
}

Modern PetstoreAPI membungkus semua koleksi dalam objek dengan metadata dan tautan HATEOAS. Lihat panduan paginasi untuk detail implementasi.

5. Standar Kesalahan yang Hilang

Pelanggaran:

Response: 400 Bad Request
{
  "code": 400,
  "message": "Invalid input"
}

Mengapa Ini Salah:

Format kesalahan ini non-standar dan memberikan informasi minimal:

Perbaikan Modern PetstoreAPI:

Response: 400 Bad Request
Content-Type: application/problem+json
{
  "type": "https://petstoreapi.com/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Request validation failed",
  "instance": "/pets",
  "errors": [
    {
      "field": "name",
      "message": "Name is required",
      "code": "REQUIRED_FIELD"
    },
    {
      "field": "status",
      "message": "Status must be one of: AVAILABLE, PENDING, SOLD",
      "code": "INVALID_ENUM"
    }
  ]
}

Modern PetstoreAPI menggunakan Detail Masalah RFC 9457 untuk semua kesalahan. Lihat panduan penanganan kesalahan untuk format kesalahan lengkap.

Bencana Keamanan dalam Desain Lama

Selain pelanggaran REST, Swagger Petstore memiliki masalah keamanan serius.

Permintaan GET dengan Kata Sandi

Pelanggaran:

GET /user/login?username=john&password=secret123

Mengapa Ini Bencana:

Kata sandi dalam permintaan GET muncul di:

Ini adalah kerentanan keamanan kritis. Kata sandi tidak boleh ada di URL.

Perbaikan Modern PetstoreAPI:

POST /auth/login
Content-Type: application/json
{
  "username": "john",
  "password": "secret123"
}

Response: 200 OK
{
  "accessToken": "eyJhbGc...",
  "refreshToken": "eyJhbGc...",
  "expiresIn": 3600
}

Modern PetstoreAPI menggunakan POST untuk autentikasi dengan body JSON. Kata sandi tidak pernah muncul di URL. Lihat panduan autentikasi untuk pola OAuth 2.0 dan JWT.

Kunci API dalam Parameter Kueri

Pelanggaran:

GET /pet/123?api_key=abc123secret

Mengapa Ini Salah:

Kunci API dalam parameter kueri memiliki masalah yang sama dengan kata sandi di URL:

Perbaikan Modern PetstoreAPI:

GET /pets/019b4132-70aa-764f-b315-e2803d882a24
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Modern PetstoreAPI menggunakan header Authorization standar untuk kunci API dan token. Lihat panduan keamanan untuk pola autentikasi.

Bagaimana Modern PetstoreAPI Memperbaiki Masalah Ini

Modern PetstoreAPI dibangun dari awal untuk menunjukkan desain API REST yang tepat. Inilah yang membuatnya berbeda:

Desain REST Siap Produksi

Standar Modern

Dukungan Multi-Protokol

Tidak seperti Swagger Petstore (hanya REST), Modern PetstoreAPI mendukung:

Lihat panduan protokol untuk detail implementasi.

Logika Bisnis Nyata

Modern PetstoreAPI menyertakan fitur-fitur realistis:

Periksa dokumentasi API untuk set fitur lengkap.

Menguji Desain API REST dengan Apidog

Apidog membantu Anda memvalidasi desain API REST dan menangkap pelanggaran sebelum mencapai produksi.

Impor dan Validasi Spesifikasi OpenAPI

# Import Modern PetstoreAPI spec
1. Open Apidog
2. Click "Import" → "OpenAPI"
3. Enter: https://petstoreapi.com/openapi.json
4. Apidog validates the spec and creates test cases

Apidog secara otomatis mendeteksi:

Uji Prinsip REST

Buat kasus uji yang memverifikasi kepatuhan REST:

Uji: Nama Sumber Daya Adalah Jamak

// Apidog test script
pm.test("Endpoint uses plural resource name", function() {
  const url = pm.request.url.toString();
  pm.expect(url).to.match(/\/pets\/|\/orders\/|\/users\//);
  pm.expect(url).to.not.match(/\/pet\/|\/order\/|\/user\//);
});

Uji: Kode Status yang Benar

pm.test("POST returns 201 Created", function() {
  if (pm.request.method === "POST") {
    pm.response.to.have.status(201);
    pm.response.to.have.header("Location");
  }
});

pm.test("DELETE returns 204 No Content", function() {
  if (pm.request.method === "DELETE") {
    pm.response.to.have.status(204);
    pm.expect(pm.response.text()).to.be.empty;
  }
});

Uji: Koleksi Memiliki Metadata

pm.test("Collection response includes pagination", function() {
  const response = pm.response.json();
  pm.expect(response).to.have.property("data");
  pm.expect(response).to.have.property("pagination");
  pm.expect(response.pagination).to.have.property("page");
  pm.expect(response.pagination).to.have.property("totalItems");
});

Bandingkan Petstore Lama vs Baru

Impor kedua spesifikasi ke Apidog dan jalankan perbandingan berdampingan:

  1. Impor Swagger Petstore: https://petstore.swagger.io/v2/swagger.json
  2. Impor Modern PetstoreAPI: https://petstoreapi.com/openapi.json
  3. Jalankan pengujian otomatis pada keduanya
  4. Bandingkan hasilnya untuk melihat perbedaannya

Apidog akan menyoroti pelanggaran desain di Swagger Petstore dan menunjukkan bagaimana Modern PetstoreAPI memperbaikinya.

Panduan Migrasi: Petstore Lama ke Desain Modern

Jika Anda membangun API berdasarkan Swagger Petstore, berikut cara bermigrasi ke desain REST yang tepat:

Langkah 1: Perbaiki Nama Sumber Daya

Sebelum:

GET /pet/{petId}
POST /pet
DELETE /pet/{petId}

Setelah:

GET /pets/{petId}
POST /pets
DELETE /pets/{petId}

Strategi Migrasi:

Langkah 2: Hapus Kata Kerja Tindakan

Sebelum:

GET /pet/findByStatus?status=available
GET /pet/findByTags?tags=tag1,tag2

Setelah:

GET /pets?status=AVAILABLE
GET /pets?tags=tag1,tag2

Strategi Migrasi:

Langkah 3: Perbaiki Kode Status HTTP

Sebelum:

POST /pet → 200 OK
DELETE /pet/{petId} → 200 OK with body

Setelah:

POST /pets → 201 Created with Location header
DELETE /pets/{petId} → 204 No Content (no body)

Strategi Migrasi:

Langkah 4: Bungkus Koleksi

Sebelum:

[
  {"id": 1, "name": "Fluffy"},
  {"id": 2, "name": "Buddy"}
]

Setelah:

{
  "data": [...],
  "pagination": {...},
  "links": {...}
}

Strategi Migrasi:

Langkah 5: Implementasikan Kesalahan RFC 9457

Sebelum:

{
  "code": 400,
  "message": "Invalid input"
}

Setelah:

{
  "type": "https://petstoreapi.com/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Request validation failed",
  "errors": [...]
}

Strategi Migrasi:

Dampak Nyata dari Desain API yang Buruk

Desain API yang buruk memiliki biaya nyata:

Kebingungan Pengembang

Ketika API melanggar prinsip REST, pengembang membuang waktu:

Biaya: Jam waktu pengembang per integrasi

Bug Klien

API yang tidak konsisten menyebabkan bug di sisi klien:

Biaya: Insiden produksi dan dampak pada pelanggan

Kerentanan Keamanan

Kekurangan desain menciptakan risiko keamanan:

Biaya: Pelanggaran data dan pelanggaran kepatuhan

Utang Teknis

Contoh yang buruk bertambah seiring waktu:

Biaya: Beban pemeliharaan jangka panjang

Kesimpulan

Swagger Petstore memenuhi tujuannya sebagai contoh OpenAPI sederhana, tetapi sudah waktunya untuk beralih. Pelanggaran REST, masalah keamanan, dan anti-polanya telah memengaruhi terlalu banyak API produksi.

Modern PetstoreAPI menyediakan implementasi referensi yang dibutuhkan industri: desain REST yang tepat, standar modern, dukungan multi-protokol, dan pola siap produksi. Gunakan sebagai sumber belajar dan referensi Anda untuk desain API.

Uji API Anda dengan Apidog untuk menangkap pelanggaran desain sejak dini. Impor spesifikasi OpenAPI Anda, jalankan pengujian otomatis, dan pastikan API Anda mengikuti prinsip REST sebelum mencapai produksi.

Langkah Selanjutnya:

  1. Jelajahi dokumentasi Modern PetstoreAPI
  2. Bandingkan desain API Anda dengan pola Modern PetstoreAPI
  3. Impor spesifikasi OpenAPI Anda ke Apidog untuk validasi
  4. Perbaiki pelanggaran REST menggunakan panduan migrasi di atas
  5. Adopsi RFC 9457 untuk penanganan kesalahan

Era contoh API yang buruk sudah berakhir. Bangun API dengan cara yang benar menggunakan Modern PetstoreAPI.

FAQ

Mengapa Swagger membuat contoh yang buruk?

Swagger Petstore dibuat pada tahun 2011 sebagai demonstrasi sederhana dari spesifikasi Swagger. Itu tidak dimaksudkan sebagai referensi desain API REST. Masalahnya adalah ia menjadi contoh standar de facto, dan kekurangannya disalin oleh jutaan pengembang.

Haruskah saya berhenti menggunakan Swagger Petstore?

Ya, untuk mempelajari desain API REST. Gunakan Modern PetstoreAPI sebagai gantinya. Ini menunjukkan prinsip REST yang tepat, standar modern, dan pola siap produksi. Petstore lama mengajarkan anti-pola yang merugikan sistem produksi.

Apakah Modern PetstoreAPI siap produksi?

Ya. Modern PetstoreAPI menyertakan logika bisnis yang realistis, penanganan kesalahan yang tepat, autentikasi, pembatasan laju, dan fitur keamanan. Anda dapat menyebarkannya dengan modifikasi minimal atau menggunakannya sebagai referensi untuk desain API Anda sendiri.

Bagaimana cara menguji apakah API saya mengikuti prinsip REST?

Impor spesifikasi OpenAPI Anda ke Apidog dan jalankan pengujian otomatis. Apidog memvalidasi penamaan sumber daya, kode status HTTP, struktur respons, dan pola keamanan. Anda juga dapat membandingkan API Anda secara berdampingan dengan Modern PetstoreAPI.

Apa kesalahan terbesar di Swagger Petstore?

Menggunakan GET /user/login dengan kata sandi dalam parameter kueri. Ini mengekspos kata sandi di riwayat browser, log server, dan header perujuk—kerentanan keamanan kritis. Selalu gunakan POST dengan body JSON untuk autentikasi.

Bisakah saya bermigrasi dari pola Swagger Petstore secara bertahap?

Ya. Dukung endpoint lama dan baru selama masa transisi. Tambahkan peringatan penghentian untuk endpoint lama, perbarui dokumentasi, dan pantau penggunaan. Hapus endpoint lama setelah klien bermigrasi (biasanya 6-12 bulan).

Apakah Modern PetstoreAPI mendukung GraphQL dan gRPC?

Ya. Tidak seperti Swagger Petstore (hanya REST), Modern PetstoreAPI mendukung berbagai protokol: REST, GraphQL, gRPC, WebSocket, SSE, MQTT, Webhook, dan MCP. Lihat panduan protokol untuk detailnya.

Bagaimana cara meyakinkan tim saya untuk memperbaiki desain API kami?

Tunjukkan kepada mereka biaya nyatanya: kebingungan pengembang, bug klien, kerentanan keamanan, dan utang teknis. Gunakan Apidog untuk menunjukkan pelanggaran dalam API Anda saat ini. Bandingkan desain Anda dengan Modern PetstoreAPI dan tunjukkan peningkatannya.

Mengembangkan API dengan Apidog

Apidog adalah alat pengembangan API yang membantu Anda mengembangkan API dengan lebih mudah dan efisien.

Daftar gratisUnduh
Mengapa Contoh Swagger Petstore Desain REST API yang Buruk?