Blog

Swagger Petstore Örneği Neden Kötü Bir REST API Tasarımı?

Ashley Innocent

Ashley Innocent

13 March 2026

Swagger Petstore Örneği Neden Kötü Bir REST API Tasarımı?

Kurumsal Apidog

Şirket İçi Dağıtım

SSO & RBAC

SOC 2 Uyumlu

Apidog Enterprise'ı Keşfet

ÖZET

Swagger Petstore temel REST prensiplerini ihlal eder: tekil kaynak adlarını tutarsız kullanır, URL'lere eylem fiilleri dahil eder, yanlış HTTP durum kodları döndürür, GET isteklerinde parolaları açığa çıkarır ve meta veri olmadan çıplak diziler döndürür. Modern PetstoreAPI, doğru RESTful tasarım, RFC 9457 hata yönetimi ve üretime hazır kalıplarla tüm bu sorunları düzeltir.

Giriş

On yılı aşkın süredir, Swagger Petstore, OpenAPI öğrenmek için varsayılan örnek olmuştur. Milyonlarca geliştirici onu inceledi, kalıplarını kopyaladı ve tasarımına dayanarak üretim API'leri oluşturdu. Tek bir sorun var: size kötü API'ler oluşturmayı öğretiyor.

Swagger Petstore temel REST prensiplerini ihlal eder, güvenlik açıklarını içerir ve üretim sistemlerine zarar veren anti-kalıpları sergiler. Bu, fren ve gaz pedalları değiştirilmiş bir arabayla araba kullanmayı öğrenmek gibidir—öğrenirsiniz, ama yanlış öğrenirsiniz.

Hasar gerçektir. Swagger Petstore'dan öğrenen geliştiriciler, bu anti-kalıpları üretim kodlarına taşırlar. API'ler tutarsız adlandırma, yanlış HTTP yöntemleri ve güvenlik delikleriyle oluşturulur. Kod incelemeleri bu sorunları gözden kaçırır çünkü "Petstore böyle yapıyor."

💡
REST API'leri oluşturuyor veya test ediyorsanız, Apidog API tasarımını REST prensiplerine göre doğrulamak, uç nokta davranışını test etmek ve üretim aşamasına gelmeden tasarım hatalarını yakalamak için size yardımcı olur. OpenAPI belirtimlerini içe aktarabilir, otomatik testler çalıştırabilir ve API'nizin doğru REST kurallarına uyduğunu sağlayabilirsiniz.
Düğme

Bu kılavuzda, Swagger Petstore'da tam olarak neyin yanlış olduğunu, bu sorunların neden önemli olduğunu ve Modern PetstoreAPI'nin üretime hazır kalıplarla bunları nasıl düzelttiğini öğreneceksiniz. Yan yana karşılaştırmalar görecek, her ihlalin etkisini anlayacak ve API'lerinizi Apidog ile doğru bir şekilde nasıl test edeceğinizi keşfedeceksiniz.

Swagger Petstore'un Eski Sorunu

Swagger Petstore, 2011 yılında Swagger spesifikasyonu (şimdiki OpenAPI) için basit bir örnek olarak oluşturuldu. Amacına hizmet etti: bir OpenAPI spesifikasyonunun nasıl yazılacağını göstermek. Ancak, hiçbir zaman REST API tasarımı için bir referans olması amaçlanmadı.

Neden Fiili Standart Haline Geldi?

Geliştiriciler OpenAPI'yi öğrendiklerinde, resmi örnekle başlarlar. Swagger Petstore bu örnektir. Belgelerde, eğitimlerde ve kod üreteçlerinde bulunur. Swagger UI veya Swagger Codegen kullandıysanız, onu görmüşsünüzdür.

Sorun şu: geliştiriciler "resmi örnek = en iyi uygulama" varsayımıyla hareket ederler. Kalıpları sorgulamadan kopyalarlar. API tasarım kursları onu bir öğretim aracı olarak kullanır. Şirketler, yapısını takip ederek dahili API'ler oluşturur.

Kötü Örneklerin Maliyeti

Kötü örnekler zamanla birikir:

  1. Genç geliştiriciler anti-kalıpları öğrenir - Bunların hata olduğunu bilmezler
  2. Kod üreteçleri sorunları sürdürür - Oluşturulan SDK'lar hataları miras alır
  3. Belgeleme araçları kötü örnekleri gösterir - Swagger UI, Petstore'u varsayılan olarak görüntüler
  4. Şirketler üretim API'lerini bu şekilde oluşturur - "Swagger için yeterince iyiyse..."

Swagger Petstore muhtemelen tarihteki diğer tüm örneklerden daha fazla API tasarımını etkilemiştir. Bu yüzden kusurları önemlidir.

Swagger Petstore'daki Kritik REST İhlalleri

Swagger Petstore'daki belirli REST ihlallerini ve bunların neden yanlış olduğunu inceleyelim.

1. Tutarsız Kaynak Adlandırması (Çoğul vs. Tekil)

İhlal:

GET /pet/{petId}           ← Tekil
GET /store/inventory       ← Çoğul
POST /pet                  ← Tekil
GET /user/{username}       ← Tekil

Neden Yanlış:

REST kaynakları koleksiyonları temsil eder. Bir koleksiyon çoğuldur. /pets'e eriştiğinizde, evcil hayvanlar koleksiyonuna erişiyorsunuz demektir. /pets/123'e eriştiğinizde, evcil hayvanlar koleksiyonundaki 123 numaralı öğeye erişiyorsunuz demektir.

Tekil ve çoğul karıştırmak bu zihinsel modeli bozar. /pet/123 evcil hayvan koleksiyonuna mı yoksa tek bir evcil hayvan kaynağına mı erişiyor? Tutarsızlık kafa karışıklığı yaratır.

Modern PetstoreAPI Düzeltmesi:

GET /pets/{petId}          ← Her zaman çoğul
GET /stores/inventory      ← Tutarlı
POST /pets                 ← Koleksiyon için çoğul
GET /users/{username}      ← Her yerde çoğul

Modern PetstoreAPI, tüm uç noktalarda çoğul kaynak adlarını tutarlı bir şekilde kullanır. Tam uç nokta yapısı için REST API belgelerine göz atın.

2. URL'lerde Eylem Fiilleri

İhlal:

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

Neden Yanlış:

REST URL'leri eylemleri (fiilleri) değil, kaynakları (isimleri) temsil etmelidir. HTTP yöntemi fiildir. GET /pets "evcil hayvanlar kaynağını al" anlamına gelir. findByStatus eklemek gereksizdir—sorgu parametreleri bunun içindir.

URL'lerdeki eylem fiilleri, REST terimleriyle değil, RPC (Uzak Prosedür Çağrısı) terimleriyle düşündüğünüzü gösterir. Kaynaklar yerine uygulama ayrıntılarını açığa çıkarıyorsunuz.

Modern PetstoreAPI Düzeltmesi:

GET /pets?status=AVAILABLE              ← Kaynak + filtre
GET /pets?tags=tag1,tag2                ← Filtreleme için sorgu parametreleri
POST /auth/login                        ← Ayrı kimlik doğrulama kaynağı
POST /auth/logout                       ← RESTful kimlik doğrulama uç noktaları

Modern PetstoreAPI, filtreleme için sorgu parametrelerini ve ayrı kimlik doğrulama kaynaklarını kullanır. Doğru kimlik doğrulama kalıpları için kimlik doğrulama kılavuzuna bakın.

3. Yanlış HTTP Durum Kodları

İhlal:

POST /pet
Response: 200 OK          ← 201 Created olmalıydı

DELETE /pet/{petId}
Response: 200 OK          ← 204 No Content olmalıydı
{
  "message": "Pet deleted"
}

Neden Yanlış:

HTTP durum kodlarının belirli anlamları vardır:

Her şey için 200 kullanmak HTTP semantiğini bozar. İstemciler "kaynak alındı" ile "kaynak oluşturuldu" arasında ayrım yapamaz. DELETE ile bir gövde döndürmek bant genişliğini boşa harcar—istemcinin onay metnine ihtiyacı yoktur.

Modern PetstoreAPI Düzeltmesi:

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
(gövdesiz)

Modern PetstoreAPI, doğru HTTP durum kodlarını kullanır ve oluşturulan kaynaklar için Location başlıklarını içerir. Tam eşleme için HTTP durum kodları kılavuzuna bakın.

4. Meta Veri Olmayan Çıplak Diziler

İhlal:

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

Neden Yanlış:

Çıplak diziler döndürmek sorunlar yaratır:

Modern PetstoreAPI Düzeltmesi:

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, tüm koleksiyonları meta veri ve HATEOAS bağlantıları içeren nesnelerle sarar. Uygulama ayrıntıları için sayfalama kılavuzuna bakın.

5. Eksik Hata Standartları

İhlal:

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

Neden Yanlış:

Bu hata formatı standart dışıdır ve minimum bilgi sağlar:

Modern PetstoreAPI Düzeltmesi:

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, tüm hatalar için RFC 9457 Problem Detaylarını kullanır. Tam hata formatı için hata işleme kılavuzuna bakın.

Eski Tasarımdaki Güvenlik Felaketleri

REST ihlallerinin ötesinde, Swagger Petstore ciddi güvenlik sorunlarına sahiptir.

Parolalarla GET İsteği

İhlal:

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

Neden Bir Felaket:

GET isteklerindeki parolalar şunlarda görünür:

Bu, kritik bir güvenlik açığıdır. Parolalar asla URL'lerde olmamalıdır.

Modern PetstoreAPI Düzeltmesi:

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

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

Modern PetstoreAPI, JSON gövdeleriyle kimlik doğrulama için POST kullanır. Parolalar asla URL'lerde görünmez. OAuth 2.0 ve JWT kalıpları için kimlik doğrulama kılavuzuna bakın.

Sorgu Parametrelerinde API Anahtarları

İhlal:

GET /pet/123?api_key=abc123secret

Neden Yanlış:

Sorgu parametrelerindeki API anahtarları, URL'lerdeki parolalarla aynı sorunlara sahiptir:

Modern PetstoreAPI Düzeltmesi:

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

Modern PetstoreAPI, API anahtarları ve token'lar için standart Authorization başlıklarını kullanır. Kimlik doğrulama kalıpları için güvenlik kılavuzuna bakın.

Modern PetstoreAPI Bu Sorunları Nasıl Çözüyor?

Modern PetstoreAPI, doğru REST API tasarımını göstermek için sıfırdan inşa edildi. Onu farklı kılan özellikler şunlardır:

Üretime Hazır REST Tasarımı

Modern Standartlar

Çoklu Protokol Desteği

Swagger Petstore'un (sadece REST) aksine, Modern PetstoreAPI şunları destekler:

Uygulama ayrıntıları için protokoller kılavuzuna bakın.

Gerçek İş Mantığı

Modern PetstoreAPI gerçekçi özellikler içerir:

Tam özellik seti için API belgelerine bakın.

Apidog ile REST API Tasarımını Test Etme

Apidog, REST API tasarımını doğrulamanıza ve üretim aşamasına gelmeden ihlalleri yakalamanıza yardımcı olur.

OpenAPI Spesifikasyonlarını İçe Aktarma ve Doğrulama

# Modern PetstoreAPI spesifikasyonunu içe aktar
1. Apidog'u açın
2. "İçe Aktar" → "OpenAPI" üzerine tıklayın
3. Şunu girin: https://petstoreapi.com/openapi.json
4. Apidog spesifikasyonu doğrular ve test senaryoları oluşturur

Apidog otomatik olarak şunları tespit eder:

REST Prensiplerini Test Etme

REST uyumluluğunu doğrulayan test senaryoları oluşturun:

Test: Kaynak Adları Çoğuldur

// Apidog test betiği
pm.test("Uç nokta çoğul kaynak adı kullanır", function() {
  const url = pm.request.url.toString();
  pm.expect(url).to.match(/\/pets\/|\/orders\/|\/users\//);
  pm.expect(url).to.not.match(/\/pet\/|\/order\/|\/user\//);
});

Test: Doğru Durum Kodları

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

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

Test: Koleksiyonlarda Meta Veri Bulunur

pm.test("Koleksiyon yanıtı sayfalama içerir", 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");
});

Eski ve Yeni Petstore'u Karşılaştırın

Her iki spesifikasyonu Apidog'a aktarın ve yan yana karşılaştırmalar yapın:

  1. Swagger Petstore'u içe aktarın: https://petstore.swagger.io/v2/swagger.json
  2. Modern PetstoreAPI'yi içe aktarın: https://petstoreapi.com/openapi.json
  3. Her ikisi üzerinde otomatik testler çalıştırın
  4. Farklılıkları görmek için sonuçları karşılaştırın

Apidog, Swagger Petstore'daki tasarım ihlallerini vurgulayacak ve Modern PetstoreAPI'nin bunları nasıl düzelttiğini gösterecektir.

Geçiş Kılavuzu: Eski Petstore'dan Modern Tasarıma

Swagger Petstore'a dayalı bir API oluşturduysanız, doğru REST tasarımına nasıl geçeceğiniz aşağıda açıklanmıştır:

Adım 1: Kaynak Adlarını Düzeltin

Önce:

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

Sonra:

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

Geçiş Stratejisi:

Adım 2: Eylem Fiillerini Kaldırın

Önce:

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

Sonra:

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

Geçiş Stratejisi:

Adım 3: HTTP Durum Kodlarını Düzeltin

Önce:

POST /pet → 200 OK
DELETE /pet/{petId} → 200 OK gövde ile

Sonra:

POST /pets → 201 Created Location başlığı ile
DELETE /pets/{petId} → 204 No Content (gövdesiz)

Geçiş Stratejisi:

Adım 4: Koleksiyonları Sarmalayın

Önce:

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

Sonra:

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

Geçiş Stratejisi:

Adım 5: RFC 9457 Hatalarını Uygulayın

Önce:

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

Sonra:

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

Geçiş Stratejisi:

Kötü API Tasarımının Gerçek Dünya Etkisi

Kötü API tasarımının gerçek maliyetleri vardır:

Geliştirici Kafa Karışıklığı

API'ler REST prensiplerini ihlal ettiğinde, geliştiriciler zaman kaybeder:

Maliyet: Her entegrasyon için saatlerce geliştirici zamanı

İstemci Hataları

Tutarsız API'ler istemci tarafı hatalarına yol açar:

Maliyet: Üretim olayları ve müşteri etkisi

Güvenlik Açıkları

Tasarım kusurları güvenlik riskleri yaratır:

Maliyet: Veri ihlalleri ve uyumluluk ihlalleri

Teknik Borç

Kötü örnekler zamanla birikir:

Maliyet: Uzun vadeli bakım yükü

Sonuç

Swagger Petstore, basit bir OpenAPI örneği olarak amacına hizmet etti, ancak artık ilerleme zamanı geldi. REST ihlalleri, güvenlik sorunları ve anti-kalıpları çok sayıda üretim API'sini etkiledi.

Modern PetstoreAPI, sektörün ihtiyaç duyduğu referans uygulamayı sunar: doğru REST tasarımı, modern standartlar, çok protokollü destek ve üretime hazır kalıplar. API tasarımı için öğrenme kaynağınız ve referansınız olarak kullanın.

API'lerinizi Apidog ile test ederek tasarım ihlallerini erken yakalayın. OpenAPI spesifikasyonlarınızı içe aktarın, otomatik testler çalıştırın ve API'lerinizin üretime geçmeden önce REST prensiplerine uygun olduğundan emin olun.

Sonraki Adımlar:

  1. Modern PetstoreAPI belgelerini keşfedin
  2. API tasarımınızı Modern PetstoreAPI kalıplarıyla karşılaştırın
  3. OpenAPI spesifikasyonunuzu doğrulama için Apidog'a aktarın
  4. Yukarıdaki geçiş kılavuzunu kullanarak REST ihlallerini düzeltin
  5. Hata yönetimi için RFC 9457'yi benimseyin

Kötü API örnekleri dönemi sona erdi. Modern PetstoreAPI ile API'leri doğru şekilde oluşturun.

Sıkça Sorulan Sorular

Swagger neden kötü bir örnek oluşturdu?

Swagger Petstore, 2011 yılında Swagger spesifikasyonunun basit bir gösterimi olarak oluşturuldu. Bir REST API tasarım referansı olması amaçlanmamıştı. Sorun şu ki, fiili standart örnek haline geldi ve kusurları milyonlarca geliştirici tarafından kopyalandı.

Swagger Petstore'u kullanmayı bırakmalı mıyım?

Evet, REST API tasarımını öğrenmek için. Bunun yerine Modern PetstoreAPI'yi kullanın. Doğru REST prensiplerini, modern standartları ve üretime hazır kalıpları gösterir. Eski Petstore, üretim sistemlerine zarar veren anti-kalıpları öğretir.

Modern PetstoreAPI üretime hazır mı?

Evet. Modern PetstoreAPI, gerçekçi iş mantığı, doğru hata işleme, kimlik doğrulama, hız sınırlama ve güvenlik özellikleri içerir. Minimum değişikliklerle dağıtabilir veya kendi API tasarımınız için referans olarak kullanabilirsiniz.

API'min REST prensiplerine uyduğunu nasıl test ederim?

OpenAPI spesifikasyonunuzu Apidog'a aktarın ve otomatik testler çalıştırın. Apidog, kaynak adlandırmayı, HTTP durum kodlarını, yanıt yapılarını ve güvenlik kalıplarını doğrular. API'nizi Modern PetstoreAPI ile yan yana da karşılaştırabilirsiniz.

Swagger Petstore'daki en büyük hata nedir?

Sorgu parametrelerinde parolalarla GET /user/login kullanılması. Bu, parolaları tarayıcı geçmişinde, sunucu günlüklerinde ve yönlendiren başlıklarında açığa çıkarır—kritik bir güvenlik açığıdır. Kimlik doğrulama için her zaman JSON gövdeleriyle POST kullanın.

Swagger Petstore kalıplarından kademeli olarak geçiş yapabilir miyim?

Evet. Geçiş süresince hem eski hem de yeni uç noktaları destekleyin. Eski uç noktalara kullanımdan kaldırma uyarıları ekleyin, belgeleri güncelleyin ve kullanımı izleyin. İstemciler geçiş yaptıktan sonra (genellikle 6-12 ay) eski uç noktaları kaldırın.

Modern PetstoreAPI GraphQL ve gRPC'yi destekliyor mu?

Evet. Swagger Petstore'un (sadece REST) aksine, Modern PetstoreAPI birden fazla protokolü destekler: REST, GraphQL, gRPC, WebSocket, SSE, MQTT, Webhooks ve MCP. Ayrıntılar için protokoller kılavuzuna bakın.

Ekibimi API tasarımımızı düzeltmeye nasıl ikna ederim?

Onlara gerçek maliyetleri gösterin: geliştirici kafa karışıklığı, istemci hataları, güvenlik açıkları ve teknik borç. Mevcut API'nizdeki ihlalleri göstermek için Apidog'u kullanın. Tasarımınızı Modern PetstoreAPI ile karşılaştırın ve iyileştirmeleri gösterin.

API Tasarım-Öncelikli Yaklaşımı Apidog'da Uygulayın

API'leri oluşturmanın ve kullanmanın daha kolay yolunu keşfedin

Ücretsiz Kaydolİndir