ทำไม Swagger Petstore ถึงเป็นตัวอย่างการออกแบบ REST API ที่ไม่ดี

สรุปโดยย่อ

Swagger Petstore ละเมิดหลักการพื้นฐานของ REST: ใช้ชื่อทรัพยากรแบบเอกพจน์อย่างไม่สอดคล้องกัน, มีคำกริยาแสดงการกระทำใน URL, ส่งคืนรหัสสถานะ HTTP ที่ไม่ถูกต้อง, เปิดเผยรหัสผ่านในการร้องขอแบบ GET, และส่งคืนอาร์เรย์เปล่าที่ไม่มีเมตาดาต้า Modern PetstoreAPI แก้ไขปัญหาทั้งหมดเหล่านี้ด้วยการออกแบบ RESTful ที่เหมาะสม, การจัดการข้อผิดพลาดตาม RFC 9457, และรูปแบบที่พร้อมสำหรับการใช้งานจริง

บทนำ

ตลอดระยะเวลาสิบกว่าปีที่ผ่านมา Swagger Petstore เป็นตัวอย่างเริ่มต้นสำหรับการเรียนรู้ OpenAPI นักพัฒนาหลายล้านคนได้ศึกษา, คัดลอกรูปแบบ, และสร้าง API ที่ใช้งานจริงโดยอิงจากการออกแบบนี้ แต่มีปัญหาหนึ่งคือ: มันสอนให้คุณสร้าง API ที่ไม่ดี

Swagger Petstore ละเมิดหลักการพื้นฐานของ REST, มีช่องโหว่ด้านความปลอดภัย, และแสดงรูปแบบที่ไม่ควรปฏิบัติ (anti-patterns) ที่เป็นอันตรายต่อระบบที่ใช้งานจริง มันเหมือนกับการเรียนขับรถที่สลับแป้นเบรกและคันเร่ง—คุณจะเรียนรู้ แต่คุณจะเรียนรู้ในทางที่ผิด

ความเสียหายนั้นเป็นเรื่องจริง นักพัฒนาที่เรียนรู้จาก Swagger Petstore ได้นำรูปแบบที่ไม่ควรปฏิบัตินี้ไปใช้ในโค้ดที่ใช้งานจริง API ถูกสร้างขึ้นด้วยการตั้งชื่อที่ไม่สอดคล้องกัน, ใช้เมธอด HTTP ที่ไม่ถูกต้อง, และมีช่องโหว่ด้านความปลอดภัย การตรวจสอบโค้ดพลาดปัญหาเหล่านี้ไปเพราะ “Petstore ก็ทำแบบนี้แหละ”

💡

หากคุณกำลังสร้างหรือทดสอบ REST API, Apidog ช่วยคุณตรวจสอบการออกแบบ API ให้สอดคล้องกับหลักการ REST, ทดสอบพฤติกรรมของเอนด์พอยต์, และตรวจจับข้อบกพร่องในการออกแบบก่อนที่จะนำไปใช้งานจริง คุณสามารถนำเข้าสเปก OpenAPI, รันการทดสอบอัตโนมัติ, และตรวจสอบให้แน่ใจว่า API ของคุณเป็นไปตามหลักการ REST ที่เหมาะสม

button

ในคู่มือนี้ คุณจะได้เรียนรู้ว่ามีอะไรผิดพลาดกับ Swagger Petstore บ้าง, ทำไมปัญหาเหล่านี้จึงสำคัญ, และ Modern PetstoreAPI แก้ไขปัญหาเหล่านี้ด้วยรูปแบบที่พร้อมสำหรับการใช้งานจริงได้อย่างไร คุณจะเห็นการเปรียบเทียบแบบคู่ขนาน, เข้าใจผลกระทบของการละเมิดแต่ละครั้ง, และค้นพบวิธีการทดสอบ API ของคุณอย่างเหมาะสมด้วย Apidog

ปัญหาของ Swagger Petstore ในอดีต

Swagger Petstore ถูกสร้างขึ้นในปี 2011 เพื่อเป็นตัวอย่างง่ายๆ สำหรับสเปกของ Swagger (ปัจจุบันคือ OpenAPI) มันทำหน้าที่ของมันได้ดี: แสดงให้เห็นถึงวิธีการเขียนสเปก OpenAPI แต่ไม่เคยมีเจตนาให้เป็นข้อมูลอ้างอิงสำหรับการออกแบบ REST API

เหตุใดจึงกลายเป็นมาตรฐานโดยพฤตินัย

เมื่อนักพัฒนาเรียนรู้ OpenAPI พวกเขาจะเริ่มต้นด้วยตัวอย่างที่เป็นทางการ Swagger Petstore คือตัวอย่างนั้น มันอยู่ในเอกสารประกอบ, บทแนะนำ, และเครื่องมือสร้างโค้ด หากคุณเคยใช้ Swagger UI หรือ Swagger Codegen คุณก็จะเคยเห็นมัน

ปัญหาคือ: นักพัฒนาสันนิษฐานว่า “ตัวอย่างทางการ = แนวปฏิบัติที่ดีที่สุด” พวกเขาคัดลอกรูปแบบโดยไม่มีคำถาม หลักสูตรการออกแบบ API ใช้มันเป็นเครื่องมือในการสอน บริษัทต่างๆ สร้าง API ภายในตามโครงสร้างของมัน

ต้นทุนของตัวอย่างที่ไม่ดี

ตัวอย่างที่ไม่ดีจะสะสมพอกพูนขึ้นเมื่อเวลาผ่านไป:

นักพัฒนารุ่นใหม่เรียนรู้รูปแบบที่ไม่ควรปฏิบัติ - พวกเขาไม่รู้ว่าสิ่งเหล่านี้คือข้อผิดพลาด
เครื่องมือสร้างโค้ดเผยแพร่ปัญหาต่อไป - SDK ที่สร้างขึ้นจะรับช่วงข้อบกพร่องไป
เครื่องมือจัดทำเอกสารแสดงตัวอย่างที่ไม่ดี - Swagger UI แสดง Petstore เป็นค่าเริ่มต้น
บริษัทต่างๆ สร้าง API ที่ใช้งานจริงด้วยวิธีนี้ - “ถ้ามันดีพอสำหรับ Swagger แล้ว...”

Swagger Petstore อาจมีอิทธิพลต่อการออกแบบ API มากกว่าตัวอย่างอื่นๆ ในประวัติศาสตร์ นั่นคือเหตุผลที่ข้อบกพร่องของมันมีความสำคัญ

การละเมิดหลักการ REST ที่สำคัญใน Swagger Petstore

มาดูกันถึงการละเมิดหลักการ REST เฉพาะใน Swagger Petstore และเหตุผลว่าทำไมจึงผิด

1. การตั้งชื่อทรัพยากรที่ไม่สอดคล้องกัน (พหูพจน์ vs เอกพจน์)

การละเมิด:

GET /pet/{petId}           ← เอกพจน์
GET /store/inventory       ← พหูพจน์
POST /pet                  ← เอกพจน์
GET /user/{username}       ← เอกพจน์

ทำไมจึงผิด:

ทรัพยากร REST แสดงถึงคอลเลกชัน คอลเลกชันเป็นพหูพจน์ เมื่อคุณเข้าถึง /pets คุณกำลังเข้าถึงคอลเลกชันของสัตว์เลี้ยง เมื่อคุณเข้าถึง /pets/123 คุณกำลังเข้าถึงรายการที่ 123 ในคอลเลกชันของสัตว์เลี้ยง

การผสมผสานระหว่างเอกพจน์และพหูพจน์ทำให้แบบจำลองนี้ผิดเพี้ยนไป /pet/123 กำลังเข้าถึงคอลเลกชันสัตว์เลี้ยง หรือทรัพยากรสัตว์เลี้ยงเดียว? ความไม่สอดคล้องกันสร้างความสับสน

การแก้ไขโดย Modern PetstoreAPI:

GET /pets/{petId}          ← เป็นพหูพจน์เสมอ
GET /stores/inventory      ← สอดคล้องกัน
POST /pets                 ← พหูพจน์สำหรับคอลเลกชัน
GET /users/{username}      ← เป็นพหูพจน์ทุกที่

Modern PetstoreAPI ใช้ชื่อทรัพยากรแบบพหูพจน์อย่างสอดคล้องกันในทุกเอนด์พอยต์ ตรวจสอบ เอกสาร REST API สำหรับโครงสร้างเอนด์พอยต์ที่สมบูรณ์

2. คำกริยาแสดงการกระทำใน URL

การละเมิด:

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

ทำไมจึงผิด:

URL ของ REST ควรแสดงถึงทรัพยากร (คำนาม) ไม่ใช่การกระทำ (คำกริยา) เมธอด HTTP คือคำกริยา GET /pets หมายถึง "ดึงทรัพยากรสัตว์เลี้ยง" การเพิ่ม findByStatus นั้นซ้ำซ้อน—นั่นคือสิ่งที่พารามิเตอร์คิวรีมีไว้สำหรับ

คำกริยาแสดงการกระทำใน URL บ่งชี้ว่าคุณกำลังคิดในแง่ของ RPC (Remote Procedure Call) ไม่ใช่ในแง่ของ REST คุณกำลังเปิดเผยรายละเอียดการใช้งานแทนที่จะเป็นทรัพยากร

การแก้ไขโดย Modern PetstoreAPI:

GET /pets?status=AVAILABLE              ← ทรัพยากร + ตัวกรอง
GET /pets?tags=tag1,tag2                ← พารามิเตอร์คิวรีสำหรับการกรอง
POST /auth/login                        ← ทรัพยากรการรับรองความถูกต้องแยกต่างหาก
POST /auth/logout                       ← เอนด์พอยต์การรับรองความถูกต้องแบบ RESTful

Modern PetstoreAPI ใช้พารามิเตอร์คิวรีสำหรับการกรองและทรัพยากรการรับรองความถูกต้องที่แยกต่างหาก ดูคู่มือการรับรองความถูกต้องสำหรับรูปแบบการรับรองความถูกต้องที่เหมาะสม

3. รหัสสถานะ HTTP ที่ไม่ถูกต้อง

การละเมิด:

POST /pet
Response: 200 OK          ← ควรจะเป็น 201 Created

DELETE /pet/{petId}
Response: 200 OK          ← ควรจะเป็น 204 No Content
{
  "message": "Pet deleted"
}

ทำไมจึงผิด:

รหัสสถานะ HTTP มีความหมายเฉพาะ:

200 OK หมายถึง "คำขอสำเร็จ, นี่คือทรัพยากร"
201 Created หมายถึง "สร้างทรัพยากรแล้ว, นี่คือที่ที่จะพบมัน"
204 No Content หมายถึง "คำขอสำเร็จ, ไม่มีเนื้อหาที่จะส่งกลับ"

การใช้ 200 สำหรับทุกอย่างเป็นการทำลายหลักความหมายของ HTTP ไคลเอ็นต์ไม่สามารถแยกแยะระหว่าง "ทรัพยากรถูกเรียกคืน" และ "ทรัพยากรถูกสร้างขึ้น" ได้ การส่งเนื้อหากลับพร้อมกับ DELETE เป็นการสิ้นเปลืองแบนด์วิธ—ไคลเอ็นต์ไม่ต้องการข้อความยืนยัน

การแก้ไขโดย 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
(ไม่มีเนื้อหา)

Modern PetstoreAPI ใช้รหัสสถานะ HTTP ที่ถูกต้องและรวมถึงเฮดเดอร์ Location สำหรับทรัพยากรที่สร้างขึ้น ตรวจสอบคู่มือรหัสสถานะ HTTP สำหรับการแมปที่สมบูรณ์

4. อาร์เรย์เปล่าที่ไม่มีเมตาดาต้า

การละเมิด:

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

ทำไมจึงผิด:

การส่งคืนอาร์เรย์เปล่าสร้างปัญหา:

ไม่มีเมตาดาต้าการแบ่งหน้า - มีรายการทั้งหมดกี่รายการ? ฉันอยู่หน้าไหน?
ไม่มีความยืดหยุ่นในการขยาย - ไม่สามารถเพิ่มเมตาดาต้าได้โดยไม่ทำให้ไคลเอ็นต์เสียหาย
ไม่มีลิงก์ HATEOAS - ไม่สามารถรวมลิงก์การนำทางได้
ความเสี่ยงจากการโจมตี JSON Hijacking - อาร์เรย์เปล่าเสี่ยงต่อการโจมตีบางประเภท

การแก้ไขโดย 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 ห่อหุ้มคอลเลกชันทั้งหมดไว้ในออบเจกต์ที่มีเมตาดาต้าและลิงก์ HATEOAS ดูคู่มือการแบ่งหน้าสำหรับรายละเอียดการใช้งาน

5. มาตรฐานข้อผิดพลาดที่ขาดหายไป

การละเมิด:

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

ทำไมจึงผิด:

รูปแบบข้อผิดพลาดนี้ไม่เป็นไปตามมาตรฐานและให้ข้อมูลน้อยมาก:

ไม่มีตัวระบุประเภทข้อผิดพลาด
ไม่มีข้อผิดพลาดในการตรวจสอบความถูกต้องระดับฟิลด์
ไม่มีรหัสข้อผิดพลาดที่เครื่องอ่านได้
ไม่เป็นไปตาม RFC 9457 (Problem Details)

การแก้ไขโดย 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 ใช้ RFC 9457 Problem Details สำหรับข้อผิดพลาดทั้งหมด ดูคู่มือการจัดการข้อผิดพลาดสำหรับรูปแบบข้อผิดพลาดที่สมบูรณ์

หายนะด้านความปลอดภัยในการออกแบบเก่า

นอกเหนือจากการละเมิดหลักการ REST แล้ว Swagger Petstore ยังมีปัญหาด้านความปลอดภัยที่ร้ายแรงอีกด้วย

การร้องขอ GET พร้อมรหัสผ่าน

การละเมิด:

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

ทำไมจึงเป็นหายนะ:

รหัสผ่านในการร้องขอ GET จะปรากฏใน:

ประวัติเบราว์เซอร์ - ใครก็ตามที่เข้าถึงเบราว์เซอร์สามารถเห็นรหัสผ่านได้
บันทึกของเซิร์ฟเวอร์ - เว็บเซิร์ฟเวอร์จะบันทึก URL เต็ม รวมถึงพารามิเตอร์คิวรี
เฮดเดอร์ Referrer - หากผู้ใช้คลิกลิงก์หลังจากเข้าสู่ระบบ เว็บไซต์ถัดไปจะเห็นรหัสผ่าน
บันทึกของพร็อกซี - พร็อกซีขององค์กรจะบันทึก URL ทั้งหมด
บุ๊กมาร์กของเบราว์เซอร์ - ผู้ใช้อาจบุ๊กมาร์ก URL การเข้าสู่ระบบ

นี่คือช่องโหว่ด้านความปลอดภัยที่สำคัญ รหัสผ่านไม่ควรอยู่ใน URL เด็ดขาด

การแก้ไขโดย Modern PetstoreAPI:

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

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

Modern PetstoreAPI ใช้ POST สำหรับการรับรองความถูกต้องด้วย JSON bodies รหัสผ่านจะไม่ปรากฏใน URL ดูคู่มือการรับรองความถูกต้องสำหรับรูปแบบ OAuth 2.0 และ JWT

คีย์ API ในพารามิเตอร์คิวรี

การละเมิด:

GET /pet/123?api_key=abc123secret

ทำไมจึงผิด:

คีย์ API ในพารามิเตอร์คิวรีมีปัญหาเช่นเดียวกับรหัสผ่านใน URL:

ถูกบันทึกไว้ทุกที่
มองเห็นได้ในประวัติเบราว์เซอร์
ถูกส่งไปในเฮดเดอร์ referrer
ถูกแคชโดยพร็อกซี

การแก้ไขโดย Modern PetstoreAPI:

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

Modern PetstoreAPI ใช้เฮดเดอร์ Authorization มาตรฐานสำหรับคีย์ API และโทเค็น ดูคู่มือความปลอดภัยสำหรับรูปแบบการรับรองความถูกต้อง

Modern PetstoreAPI แก้ไขปัญหาเหล่านี้ได้อย่างไร

Modern PetstoreAPI ถูกสร้างขึ้นใหม่ทั้งหมดเพื่อแสดงให้เห็นถึงการออกแบบ REST API ที่เหมาะสม นี่คือสิ่งที่ทำให้มันแตกต่าง:

การออกแบบ REST ที่พร้อมใช้งานจริง

ชื่อทรัพยากรพหูพจน์ที่สอดคล้องกัน - /pets, /orders, /users
URL ที่เน้นทรัพยากร - ไม่มีคำกริยาแสดงการกระทำ, มีแต่คำนาม
รหัสสถานะ HTTP ที่ถูกต้อง - 201 สำหรับการสร้าง, 204 สำหรับการลบ, รหัสข้อผิดพลาดที่เหมาะสม
ตัวห่อหุ้มคอลเลกชัน - รายการทั้งหมดมีข้อมูลการแบ่งหน้าและเมตาดาต้า
ข้อผิดพลาด RFC 9457 - รูปแบบข้อผิดพลาดมาตรฐานพร้อมการตรวจสอบความถูกต้องระดับฟิลด์

มาตรฐานที่ทันสมัย

OpenAPI 3.2 - สเปกเวอร์ชันล่าสุดพร้อมคุณสมบัติทั้งหมด
RFC 9457 - รายละเอียดปัญหาสำหรับ HTTP API
การจำกัดอัตรา (Rate Limiting) ของ IETF - เฮดเดอร์ RateLimit-* มาตรฐาน
ISO 8601 - รูปแบบวันที่/เวลาที่เหมาะสม
UUIDv7 - ตัวระบุที่ไม่ซ้ำกันที่เรียงลำดับได้

การรองรับหลายโปรโตคอล

แตกต่างจาก Swagger Petstore (รองรับเฉพาะ REST), Modern PetstoreAPI รองรับ:

REST (OpenAPI 3.2)
GraphQL
gRPC
WebSocket
Server-Sent Events (SSE)
MQTT
Webhooks
Model Context Protocol (MCP)

ดูคู่มือโปรโตคอลสำหรับรายละเอียดการใช้งาน

ตรรกะทางธุรกิจที่แท้จริง

Modern PetstoreAPI มีคุณสมบัติที่สมจริง:

การประมวลผลการชำระเงิน
การจัดการสินค้าคงคลัง
การจัดการคำสั่งซื้อ
การแจ้งเตือน Webhook
คำแนะนำสัตว์เลี้ยงที่ขับเคลื่อนด้วย AI
การอัปโหลดและประมวลผลรูปภาพ

ตรวจสอบเอกสาร API สำหรับชุดคุณสมบัติที่สมบูรณ์

การทดสอบการออกแบบ REST API ด้วย Apidog

Apidog ช่วยคุณตรวจสอบการออกแบบ REST API และตรวจจับการละเมิดก่อนที่จะนำไปใช้งานจริง

นำเข้าและตรวจสอบ OpenAPI Specs

# นำเข้าสเปก Modern PetstoreAPI
1. เปิด Apidog
2. คลิก "Import" → "OpenAPI"
3. ป้อน: https://petstoreapi.com/openapi.json
4. Apidog ตรวจสอบสเปกและสร้างกรณีทดสอบ

Apidog ตรวจจับโดยอัตโนมัติ:

การตั้งชื่อทรัพยากรที่ไม่สอดคล้องกัน
รหัสสถานะ HTTP ที่ขาดหายไป
โครงสร้างการตอบกลับที่ไม่ถูกต้อง
ปัญหาด้านความปลอดภัยในการรับรองความถูกต้อง

ทดสอบหลักการ REST

สร้างกรณีทดสอบที่ตรวจสอบการปฏิบัติตามหลัก REST:

ทดสอบ: ชื่อทรัพยากรเป็นพหูพจน์

// สคริปต์ทดสอบของ Apidog
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\//);
});

ทดสอบ: รหัสสถานะที่ถูกต้อง

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;
  }
});

ทดสอบ: คอลเลกชันมีเมตาดาต้า

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");
});

เปรียบเทียบ Petstore เก่ากับใหม่

นำเข้าสเปกทั้งสองลงใน Apidog และรันการเปรียบเทียบแบบคู่ขนาน:

นำเข้า Swagger Petstore: https://petstore.swagger.io/v2/swagger.json
นำเข้า Modern PetstoreAPI: https://petstoreapi.com/openapi.json
รันการทดสอบอัตโนมัติบนทั้งสอง
เปรียบเทียบผลลัพธ์เพื่อดูความแตกต่าง

Apidog จะเน้นย้ำถึงการละเมิดการออกแบบใน Swagger Petstore และแสดงให้เห็นว่า Modern PetstoreAPI แก้ไขปัญหาเหล่านั้นได้อย่างไร

คู่มือการย้ายระบบ: จาก Petstore เก่าสู่การออกแบบที่ทันสมัย

หากคุณสร้าง API โดยอิงจาก Swagger Petstore นี่คือวิธีการย้ายไปสู่การออกแบบ REST ที่เหมาะสม:

ขั้นตอนที่ 1: แก้ไขชื่อทรัพยากร

ก่อน:

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

หลัง:

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

กลยุทธ์การย้ายระบบ:

รองรับทั้งสองเอนด์พอยต์ในช่วงเปลี่ยนผ่าน
เพิ่มคำเตือนการเลิกใช้งานไปยังเอนด์พอยต์เก่า
อัปเดตเอกสารเพื่อแสดงเอนด์พอยต์ใหม่
ติดตามการใช้งานและลบเอนด์พอยต์เก่าหลังจาก 6 เดือน

ขั้นตอนที่ 2: ลบคำกริยาแสดงการกระทำ

ก่อน:

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

หลัง:

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

กลยุทธ์การย้ายระบบ:

เปลี่ยนเส้นทางเอนด์พอยต์เก่าไปยังเอนด์พอยต์ใหม่ด้วย 301 Moved Permanently
อัปเดต client SDKs ให้ใช้เอนด์พอยต์ใหม่
เพิ่มการตรวจสอบพารามิเตอร์คิวรี

ขั้นตอนที่ 3: แก้ไขรหัสสถานะ HTTP

ก่อน:

POST /pet → 200 OK
DELETE /pet/{petId} → 200 OK พร้อมเนื้อหา

หลัง:

POST /pets → 201 Created พร้อมเฮดเดอร์ Location
DELETE /pets/{petId} → 204 No Content (ไม่มีเนื้อหา)

กลยุทธ์การย้ายระบบ:

นี่เป็นการเปลี่ยนแปลงที่ส่งผลกระทบต่อไคลเอ็นต์ที่ตรวจสอบรหัสสถานะ
กำหนดเวอร์ชัน API ของคุณ (v2) ด้วยรหัสสถานะที่ถูกต้อง
จัดทำเอกสารการเปลี่ยนแปลงให้ชัดเจน
ระบุไทม์ไลน์การย้ายระบบ

ขั้นตอนที่ 4: ห่อหุ้มคอลเลกชัน

ก่อน:

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

หลัง:

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

กลยุทธ์การย้ายระบบ:

นี่เป็นการเปลี่ยนแปลงที่ส่งผลกระทบ
สร้างเอนด์พอยต์ v2 พร้อมการตอบกลับที่ห่อหุ้ม
เลิกใช้งานเอนด์พอยต์ v1
อัปเดตโค้ดไคลเอ็นต์เพื่อรองรับโครงสร้างใหม่

ขั้นตอนที่ 5: นำ RFC 9457 Errors มาใช้

ก่อน:

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

หลัง:

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

กลยุทธ์การย้ายระบบ:

เพิ่มเฮดเดอร์ Content-Type: application/problem+json
รวมรูปแบบข้อผิดพลาดทั้งเก่าและใหม่ในช่วงเปลี่ยนผ่าน
อัปเดตการจัดการข้อผิดพลาดของไคลเอ็นต์
ลบรูปแบบเก่าหลังจากช่วงเวลาการย้ายระบบ

ผลกระทบจริงของการออกแบบ API ที่ไม่ดี

การออกแบบ API ที่ไม่ดีมีต้นทุนที่แท้จริง:

ความสับสนของนักพัฒนา

เมื่อ API ละเมิดหลักการ REST นักพัฒนาจะเสียเวลาไปกับ:

คาดเดาว่าจะใช้เมธอด HTTP ใด
ทำความเข้าใจรูปแบบการตั้งชื่อที่ไม่สอดคล้องกัน
ดีบักรหัสสถานะที่ไม่คาดคิด
จัดการข้อผิดพลาดโดยไม่มีโครงสร้างที่เหมาะสม

ต้นทุน: ชั่วโมงการทำงานของนักพัฒนาต่อการรวมระบบ

ข้อผิดพลาดของไคลเอ็นต์

API ที่ไม่สอดคล้องกันนำไปสู่ข้อผิดพลาดฝั่งไคลเอ็นต์:

ข้อผิดพลาดในการแยกวิเคราะห์จากโครงสร้างการตอบกลับที่ไม่คาดคิด
การรับรองความถูกต้องล้มเหลวจากเมธอด HTTP ที่ไม่ถูกต้อง
ปัญหาการแบ่งหน้าจากเมตาดาต้าที่ขาดหายไป
การจัดการข้อผิดพลาดล้มเหลวจากรูปแบบที่ไม่เป็นไปตามมาตรฐาน

ต้นทุน: เหตุการณ์ที่เกิดขึ้นในการผลิตและผลกระทบต่อลูกค้า

ช่องโหว่ด้านความปลอดภัย

ข้อบกพร่องในการออกแบบสร้างความเสี่ยงด้านความปลอดภัย:

รหัสผ่านใน URL ถูกบันทึก
คีย์ API ในพารามิเตอร์คิวรีถูกแคช
การรับรองความถูกต้องขาดหายไปบนเอนด์พอยต์ที่ละเอียดอ่อน
ข้อความแสดงข้อผิดพลาดที่ไม่เหมาะสมรั่วไหลข้อมูลระบบ

ต้นทุน: การละเมิดข้อมูลและการฝ่าฝืนกฎระเบียบ

หนี้ทางเทคนิค

ตัวอย่างที่ไม่ดีจะสะสมพอกพูนขึ้นเมื่อเวลาผ่านไป:

นักพัฒนาใหม่เรียนรู้รูปแบบที่ไม่ควรปฏิบัติ
เครื่องมือสร้างโค้ดผลิต SDK ที่มีข้อบกพร่อง
เอกสารแสดงตัวอย่างที่ไม่ถูกต้อง
บริษัทต่างๆ สร้าง API ใหม่ด้วยข้อผิดพลาดเดิมๆ

ต้นทุน: ภาระการบำรุงรักษาในระยะยาว

สรุป

Swagger Petstore ทำหน้าที่เป็นตัวอย่าง OpenAPI ที่เรียบง่าย แต่ถึงเวลาต้องก้าวไปข้างหน้า การละเมิดหลักการ REST, ปัญหาด้านความปลอดภัย, และรูปแบบที่ไม่ควรปฏิบัติของมันมีอิทธิพลต่อ API ที่ใช้งานจริงมากเกินไป

Modern PetstoreAPI มอบการใช้งานอ้างอิงที่อุตสาหกรรมต้องการ: การออกแบบ REST ที่เหมาะสม, มาตรฐานที่ทันสมัย, การรองรับหลายโปรโตคอล, และรูปแบบที่พร้อมสำหรับการใช้งานจริง ใช้เป็นแหล่งเรียนรู้และข้อมูลอ้างอิงสำหรับการออกแบบ API ของคุณ

ทดสอบ API ของคุณด้วย Apidog เพื่อตรวจจับการละเมิดการออกแบบตั้งแต่เนิ่นๆ นำเข้าสเปก OpenAPI ของคุณ, รันการทดสอบอัตโนมัติ, และตรวจสอบให้แน่ใจว่า API ของคุณเป็นไปตามหลักการ REST ก่อนที่จะนำไปใช้งานจริง

ขั้นตอนถัดไป:

สำรวจเอกสารประกอบ Modern PetstoreAPI
เปรียบเทียบการออกแบบ API ของคุณกับรูปแบบของ Modern PetstoreAPI
นำเข้าสเปก OpenAPI ของคุณลงใน Apidog เพื่อตรวจสอบความถูกต้อง
แก้ไขการละเมิดหลักการ REST โดยใช้คู่มือการย้ายระบบด้านบน
นำ RFC 9457 มาใช้สำหรับการจัดการข้อผิดพลาด

ยุคของตัวอย่าง API ที่ไม่ดีสิ้นสุดลงแล้ว สร้าง API อย่างถูกวิธีด้วย Modern PetstoreAPI

คำถามที่พบบ่อย

เหตุใด Swagger จึงสร้างตัวอย่างที่ไม่ดี?

Swagger Petstore ถูกสร้างขึ้นในปี 2011 เพื่อแสดงให้เห็นถึงสเปกของ Swagger แบบง่ายๆ มันไม่ได้มีเจตนาให้เป็นข้อมูลอ้างอิงสำหรับการออกแบบ REST API ปัญหาคือมันได้กลายเป็นตัวอย่างมาตรฐานโดยพฤตินัย และข้อบกพร่องของมันก็ถูกคัดลอกโดยนักพัฒนาหลายล้านคน

ฉันควรหยุดใช้ Swagger Petstore หรือไม่?

ใช่ สำหรับการเรียนรู้การออกแบบ REST API ให้ใช้ Modern PetstoreAPI แทน มันแสดงให้เห็นถึงหลักการ REST ที่เหมาะสม, มาตรฐานที่ทันสมัย, และรูปแบบที่พร้อมสำหรับการใช้งานจริง Petstore เก่าสอนรูปแบบที่ไม่ควรปฏิบัติที่เป็นอันตรายต่อระบบที่ใช้งานจริง

Modern PetstoreAPI พร้อมสำหรับการใช้งานจริงหรือไม่?

ใช่ Modern PetstoreAPI มีตรรกะทางธุรกิจที่สมจริง, การจัดการข้อผิดพลาดที่เหมาะสม, การรับรองความถูกต้อง, การจำกัดอัตรา, และคุณสมบัติความปลอดภัย คุณสามารถนำไปใช้งานได้โดยมีการปรับเปลี่ยนน้อยที่สุด หรือใช้เป็นข้อมูลอ้างอิงสำหรับการออกแบบ API ของคุณเอง

ฉันจะทดสอบได้อย่างไรว่า API ของฉันเป็นไปตามหลักการ REST?

นำเข้าสเปก OpenAPI ของคุณลงใน Apidog และรันการทดสอบอัตโนมัติ Apidog ตรวจสอบความถูกต้องของการตั้งชื่อทรัพยากร, รหัสสถานะ HTTP, โครงสร้างการตอบกลับ, และรูปแบบความปลอดภัย คุณยังสามารถเปรียบเทียบ API ของคุณแบบคู่ขนานกับ Modern PetstoreAPI ได้อีกด้วย

ข้อผิดพลาดที่ใหญ่ที่สุดใน Swagger Petstore คืออะไร?

การใช้ GET /user/login โดยมีรหัสผ่านอยู่ในพารามิเตอร์คิวรี ซึ่งเป็นการเปิดเผยรหัสผ่านในประวัติเบราว์เซอร์, บันทึกของเซิร์ฟเวอร์, และเฮดเดอร์ referrer—เป็นช่องโหว่ด้านความปลอดภัยที่สำคัญ ควรใช้ POST พร้อม JSON bodies สำหรับการรับรองความถูกต้องเสมอ

ฉันสามารถย้ายจากรูปแบบ Swagger Petstore ได้อย่างค่อยเป็นค่อยไปหรือไม่?

ใช่ รองรับทั้งเอนด์พอยต์เก่าและใหม่ในช่วงเปลี่ยนผ่าน เพิ่มคำเตือนการเลิกใช้งานไปยังเอนด์พอยต์เก่า, อัปเดตเอกสาร, และติดตามการใช้งาน ลบเอนด์พอยต์เก่าหลังจากไคลเอ็นต์ได้ย้ายระบบแล้ว (โดยทั่วไปคือ 6-12 เดือน)

Modern PetstoreAPI รองรับ GraphQL และ gRPC หรือไม่?

ใช่ แตกต่างจาก Swagger Petstore (รองรับเฉพาะ REST), Modern PetstoreAPI รองรับหลายโปรโตคอล: REST, GraphQL, gRPC, WebSocket, SSE, MQTT, Webhooks, และ MCP ดูคู่มือโปรโตคอลสำหรับรายละเอียด

ฉันจะโน้มน้าวทีมให้แก้ไขการออกแบบ API ของเราได้อย่างไร?

แสดงให้พวกเขาเห็นถึงต้นทุนที่แท้จริง: ความสับสนของนักพัฒนา, ข้อผิดพลาดของไคลเอ็นต์, ช่องโหว่ด้านความปลอดภัย, และหนี้ทางเทคนิค ใช้ Apidog เพื่อแสดงให้เห็นถึงการละเมิดใน API ปัจจุบันของคุณ เปรียบเทียบการออกแบบของคุณกับ Modern PetstoreAPI และแสดงให้เห็นถึงการปรับปรุง