สรุปย่อ
RFC 9457 (รายละเอียดปัญหาสำหรับ HTTP API) เป็นรูปแบบมาตรฐานสำหรับการตอบกลับข้อผิดพลาดของ API โดยจะเข้ามาแทนที่รูปแบบข้อผิดพลาดที่กำหนดเองด้วยโครงสร้างที่สอดคล้องกัน: type, title, status, detail และ instance Modern PetstoreAPI นำ RFC 9457 มาใช้กับการตอบกลับข้อผิดพลาดทั้งหมด พร้อมการเจรจาเนื้อหาและรายละเอียดการตรวจสอบที่เหมาะสม
บทนำ
API ของคุณส่งคืนข้อผิดพลาด การตอบกลับมีลักษณะอย่างไร? หากคุณเป็นเหมือน API ส่วนใหญ่ คุณก็คงสร้างรูปแบบของคุณเองขึ้นมา:
{"error": "Invalid email"}
{"message": "Not found", "code": 404}
{"success": false, "errors": ["Email required"]}
API ทุกตัวมีรูปแบบข้อผิดพลาดที่แตกต่างกัน ลูกค้าจำเป็นต้องมีการจัดการข้อผิดพลาดที่กำหนดเองสำหรับแต่ละ API ไม่มีวิธีมาตรฐานในการแยกวิเคราะห์ข้อผิดพลาด แสดงให้ผู้ใช้เห็น หรือบันทึกเพื่อการดีบัก
RFC 9457 แก้ปัญหานี้ได้ เป็นมาตรฐาน IETF ที่กำหนดว่า API ควรส่งคืนข้อผิดพลาดอย่างไร แทนที่จะสร้างรูปแบบของคุณเอง คุณสามารถใช้มาตรฐานที่ได้รับการพิสูจน์แล้วที่ลูกค้าเข้าใจอยู่แล้ว
Swagger Petstore แบบเก่าใช้รูปแบบข้อผิดพลาดที่กำหนดเองโดยไม่มีความสอดคล้องกัน Modern PetstoreAPI ใช้ RFC 9457 กับการตอบกลับข้อผิดพลาดทั้งหมด โดยให้รายละเอียดข้อผิดพลาดที่มีโครงสร้างและเครื่องอ่านได้
ในคู่มือนี้ คุณจะได้เรียนรู้ว่า RFC 9457 คืออะไร วิธีการนำไปใช้อย่างถูกต้อง และ Modern PetstoreAPI ใช้งานอย่างไรสำหรับการตอบกลับข้อผิดพลาดทั้งหมด
ปัญหาข้อผิดพลาดของ API
ก่อนหน้า RFC 9457, ทุก API สร้างรูปแบบข้อผิดพลาดของตนเองขึ้นมา
รูปแบบข้อผิดพลาดที่พบบ่อย
รูปแบบที่ 1: ข้อความธรรมดา
{"error": "User not found"}
รูปแบบที่ 2: รหัสและข้อความ
{"code": "USER_NOT_FOUND", "message": "User not found"}
รูปแบบที่ 3: โครงสร้างซ้อนกัน
{
"success": false,
"error": {
"type": "NotFound",
"message": "User not found"
}
}
รูปแบบที่ 4: อาร์เรย์ของข้อผิดพลาด
{
"errors": [
{"field": "email", "message": "Invalid email"}
]
}
ปัญหาของรูปแบบที่กำหนดเอง
1. ไม่มีความสอดคล้องกัน: ลูกค้าจำเป็นต้องมีการแยกวิเคราะห์แบบกำหนดเองสำหรับแต่ละ API
2. ข้อมูลขาดหายไป: บางรูปแบบขาดรหัสข้อผิดพลาด บางรูปแบบขาดรายละเอียด บางรูปแบบขาดทั้งสองอย่าง
3. ไม่มีโครงสร้างที่เครื่องอ่านได้: จัดการข้อผิดพลาดด้วยโปรแกรมได้ยาก
4. การทำให้เป็นสากลไม่ดี: ข้อความข้อผิดพลาดถูกฮาร์ดโค้ดเป็นภาษาอังกฤษ
5. ไม่มีมาตรฐานสำหรับข้อผิดพลาดในการตรวจสอบ: แต่ละ API จัดการข้อผิดพลาดระดับฟิลด์แตกต่างกันไป
RFC 9457 คืออะไร?
RFC 9457 (เผยแพร่เมื่อเดือนกรกฎาคม 2023) กำหนด "รายละเอียดปัญหาสำหรับ HTTP API" เป็นมาตรฐาน IETF ที่ระบุว่า API ควรจัดโครงสร้างการตอบกลับข้อผิดพลาดอย่างไร
คุณสมบัติหลัก
ประเภทสื่อมาตรฐาน: application/problem+json (หรือ application/problem+xml)
โครงสร้างที่สอดคล้องกัน: ข้อผิดพลาดทั้งหมดใช้รูปแบบเดียวกัน
เครื่องอ่านได้: ลูกค้าสามารถแยกวิเคราะห์ข้อผิดพลาดด้วยโปรแกรม
ขยายได้: คุณสามารถเพิ่มฟิลด์ที่กำหนดเองได้ในขณะที่ยังคงความเข้ากันได้
รองรับ HTTP: ผสานรวมกับรหัสสถานะ HTTP
RFC 9457 กับ ข้อผิดพลาดที่กำหนดเอง
ข้อผิดพลาดที่กำหนดเอง:
{"error": "Email is required"}
ข้อผิดพลาด RFC 9457:
{
"type": "https://petstoreapi.com/errors/validation-error",
"title": "Validation Error",
"status": 400,
"detail": "The request contains invalid data",
"instance": "/pets",
"errors": [
{
"field": "email",
"message": "Email is required"
}
]
}
เวอร์ชัน RFC 9457 ให้สิ่งต่อไปนี้:
- URL ประเภทข้อผิดพลาดสำหรับเอกสารประกอบ
- ชื่อที่มนุษย์อ่านได้
- รหัสสถานะ HTTP
- คำอธิบายโดยละเอียด
- พาธคำขอที่ทำให้เกิดข้อผิดพลาด
- รายละเอียดการตรวจสอบระดับฟิลด์
โครงสร้าง RFC 9457 อธิบาย
RFC 9457 กำหนดห้าฟิลด์มาตรฐานและอนุญาตให้มีการขยายแบบกำหนดเอง
ฟิลด์มาตรฐาน
1. type (สตริง, จำเป็น)
การอ้างอิง URI ที่ระบุประเภทข้อผิดพลาด ควรชี้ไปยังเอกสารประกอบที่มนุษย์อ่านได้
"type": "https://petstoreapi.com/errors/validation-error"
หากละเว้น จะใช้ค่าเริ่มต้นเป็น about:blank
2. title (สตริง, จำเป็น)
สรุปย่อที่มนุษย์อ่านได้ของประเภทข้อผิดพลาด ไม่ควรเปลี่ยนแปลงระหว่างเหตุการณ์
"title": "Validation Error"
3. status (ตัวเลข, จำเป็น)
รหัสสถานะ HTTP รวมอยู่ด้วยเพื่อความสะดวก ลูกค้าจึงไม่จำเป็นต้องแยกวิเคราะห์ส่วนหัว
"status": 400
4. detail (สตริง, ไม่บังคับ)
คำอธิบายที่มนุษย์อ่านได้ซึ่งเฉพาะเจาะจงสำหรับเหตุการณ์ข้อผิดพลาดนี้
"detail": "The email field must be a valid email address"
5. instance (สตริง, ไม่บังคับ)
การอ้างอิง URI ที่ระบุเหตุการณ์เฉพาะของข้อผิดพลาด บ่อยครั้งคือพาธคำขอ
"instance": "/pets/019b4132-70aa-764f-b315-e2803d882a24"
ส่วนขยายที่กำหนดเอง
คุณสามารถเพิ่มฟิลด์ที่กำหนดเองสำหรับบริบทเพิ่มเติม:
{
"type": "https://petstoreapi.com/errors/rate-limit-exceeded",
"title": "Rate Limit Exceeded",
"status": 429,
"detail": "You have exceeded the rate limit of 100 requests per minute",
"instance": "/pets",
"retryAfter": 42,
"limit": 100,
"remaining": 0,
"resetAt": "2026-03-13T10:30:00Z"
}
Modern PetstoreAPI นำ RFC 9457 มาใช้อย่างไร
Modern PetstoreAPI ใช้ RFC 9457 สำหรับการตอบกลับข้อผิดพลาดทั้งหมด
ตัวอย่างที่ 1: ไม่พบทรัพยากร
GET /pets/invalid-id
404 Not Found
Content-Type: application/problem+json
{
"type": "https://docs.petstoreapi.com/errors/not-found",
"title": "Resource Not Found",
"status": 404,
"detail": "The requested pet does not exist",
"instance": "/pets/invalid-id"
}
ตัวอย่างที่ 2: ข้อผิดพลาดในการยืนยันตัวตน
GET /pets
401 Unauthorized
Content-Type: application/problem+json
{
"type": "https://docs.petstoreapi.com/errors/unauthorized",
"title": "Authentication Required",
"status": 401,
"detail": "Valid authentication credentials are required to access this resource",
"instance": "/pets"
}
ตัวอย่างที่ 3: เกินขีดจำกัดอัตรา
GET /pets
429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 60
{
"type": "https://docs.petstoreapi.com/errors/rate-limit-exceeded",
"title": "Rate Limit Exceeded",
"status": 429,
"detail": "You have exceeded the rate limit of 100 requests per minute",
"instance": "/pets",
"limit": 100,
"remaining": 0,
"resetAt": "2026-03-13T10:31:00Z"
}
ดู เอกสารการจัดการข้อผิดพลาดของ Modern PetstoreAPI สำหรับประเภทข้อผิดพลาดทั้งหมด
ข้อผิดพลาดในการตรวจสอบด้วย RFC 9457
ข้อผิดพลาดในการตรวจสอบต้องการรายละเอียดระดับฟิลด์ RFC 9457 อนุญาตให้มีการขยายแบบกำหนดเองสำหรับเรื่องนี้
รูปแบบการตรวจสอบของ Modern PetstoreAPI
POST /pets
400 Bad Request
Content-Type: application/problem+json
{
"type": "https://docs.petstoreapi.com/errors/validation-error",
"title": "Validation Error",
"status": 400,
"detail": "The request contains 2 validation errors",
"instance": "/pets",
"errors": [
{
"field": "name",
"message": "Name is required",
"code": "REQUIRED_FIELD"
},
{
"field": "species",
"message": "Species must be one of: DOG, CAT, BIRD, FISH, REPTILE, OTHER",
"code": "INVALID_ENUM_VALUE",
"rejectedValue": "DRAGON"
}
]
}
ประเด็นสำคัญ
อาร์เรย์ errors: มีรายละเอียดการตรวจสอบระดับฟิลด์
field: พาธ JSON ไปยังฟิลด์ที่ไม่ถูกต้อง
message: ข้อความข้อผิดพลาดที่มนุษย์อ่านได้
code: รหัสข้อผิดพลาดที่เครื่องอ่านได้
rejectedValue: ค่าที่ถูกปฏิเสธ (ไม่บังคับ)
รูปแบบนี้ช่วยให้ลูกค้าสามารถ:
- แสดงข้อผิดพลาดระดับฟิลด์ในฟอร์ม
- เน้นฟิลด์ที่ไม่ถูกต้อง
- ระบุข้อความข้อผิดพลาดเฉพาะเจาะจง
- จัดการข้อผิดพลาดด้วยโปรแกรม
การทดสอบการตอบกลับข้อผิดพลาดด้วย Apidog
Apidog ช่วยให้คุณทดสอบการปฏิบัติตาม RFC 9457
กรณีทดสอบ: ข้อผิดพลาดในการตรวจสอบ
// Apidog test script
pm.test("Returns RFC 9457 error format", () => {
const response = pm.response.json();
// Check required fields
pm.expect(response).to.have.property("type");
pm.expect(response).to.have.property("title");
pm.expect(response).to.have.property("status");
// Check status matches HTTP status
pm.expect(response.status).to.equal(pm.response.code);
// Check content type
pm.expect(pm.response.headers.get("Content-Type"))
.to.include("application/problem+json");
});
pm.test("Validation errors include field details", () => {
const response = pm.response.json();
pm.expect(response).to.have.property("errors");
pm.expect(response.errors).to.be.an("array");
response.errors.forEach(error => {
pm.expect(error).to.have.property("field");
pm.expect(error).to.have.property("message");
});
});
กรณีทดสอบ: URL ประเภทข้อผิดพลาด
pm.test("Error type URL is accessible", async () => {
const response = pm.response.json();
const typeUrl = response.type;
// Verify type URL returns documentation
const docResponse = await pm.sendRequest(typeUrl);
pm.expect(docResponse.code).to.equal(200);
});
การย้ายจากรูปแบบข้อผิดพลาดที่กำหนดเอง
หากคุณกำลังใช้รูปแบบข้อผิดพลาดที่กำหนดเอง นี่คือวิธีที่จะย้ายไปยัง RFC 9457
ขั้นตอนที่ 1: เพิ่มส่วนหัว Content-Type
เริ่มส่งคืน application/problem+json:
Content-Type: application/problem+json
ขั้นตอนที่ 2: จับคู่ฟิลด์ที่มีอยู่
จับคู่รูปแบบที่คุณกำหนดเองกับ RFC 9457:
ก่อน:
{
"error": "USER_NOT_FOUND",
"message": "User not found"
}
หลัง:
{
"type": "https://api.example.com/errors/user-not-found",
"title": "User Not Found",
"status": 404,
"detail": "User not found"
}
ขั้นตอนที่ 3: รองรับทั้งสองรูปแบบ (ช่วงเวลาเปลี่ยนผ่าน)
ใช้การเจรจาเนื้อหาเพื่อรองรับทั้งสองรูปแบบ:
Accept: application/json → ส่งคืนรูปแบบที่กำหนดเอง
Accept: application/problem+json → ส่งคืนรูปแบบ RFC 9457
ขั้นตอนที่ 4: เลิกใช้รูปแบบที่กำหนดเอง
หลังจากลูกค้าโยกย้ายแล้ว ให้เลิกใช้รูปแบบที่กำหนดเองและส่งคืน RFC 9457 เป็นค่าเริ่มต้น
สรุป
RFC 9457 มอบรูปแบบมาตรฐานสำหรับการตอบกลับข้อผิดพลาดของ API โดยจะเข้ามาแทนที่รูปแบบข้อผิดพลาดที่กำหนดเองด้วยโครงสร้างที่สอดคล้องกันและเครื่องอ่านได้ ซึ่งลูกค้าสามารถแยกวิเคราะห์ด้วยโปรแกรมได้
Modern PetstoreAPI ใช้ RFC 9457 กับการตอบกลับข้อผิดพลาดทั้งหมด โดยแสดงให้เห็นถึงวิธีการจัดโครงสร้างข้อผิดพลาดอย่างถูกต้องพร้อมรายละเอียดการตรวจสอบที่เหมาะสม, URL ประเภทข้อผิดพลาด, และรหัสสถานะ HTTP
ใช้ Apidog เพื่อทดสอบการปฏิบัติตาม RFC 9457, ตรวจสอบโครงสร้างข้อผิดพลาด, และรับรองว่า API ของคุณส่งคืนการตอบกลับข้อผิดพลาดที่ถูกต้อง
คำถามที่พบบ่อย
RFC 9457 จำเป็นสำหรับ REST API หรือไม่?
ไม่ แต่เป็นมาตรฐานที่แนะนำ การใช้ RFC 9457 ทำให้ API ของคุณสอดคล้องกันมากขึ้นและลูกค้าสามารถรวมเข้าด้วยกันได้ง่ายขึ้น
ฉันสามารถใช้ RFC 9457 กับ XML ได้หรือไม่?
ได้ RFC 9457 กำหนดทั้งรูปแบบ JSON (application/problem+json) และ XML (application/problem+xml)
ฉันควรจะรวมฟิลด์มาตรฐานทั้งห้าฟิลด์เสมอหรือไม่?
type, title และ status เป็นฟิลด์ที่จำเป็น detail และ instance เป็นฟิลด์ที่ไม่บังคับแต่แนะนำเพื่อให้บริบทของข้อผิดพลาดดีขึ้น
ฉันสามารถเพิ่มฟิลด์ที่กำหนดเองในการตอบกลับ RFC 9457 ได้หรือไม่?
ได้ RFC 9457 สามารถขยายได้ คุณสามารถเพิ่มฟิลด์ที่กำหนดเอง เช่น errors, retryAfter หรือ traceId สำหรับบริบทเพิ่มเติม
ฉันจะจัดการข้อผิดพลาดในการตรวจสอบด้วย RFC 9457 ได้อย่างไร?
เพิ่มอาร์เรย์ errors ที่กำหนดเองพร้อมรายละเอียดระดับฟิลด์ Modern PetstoreAPI แสดงรูปแบบนี้ในการตอบกลับข้อผิดพลาดในการตรวจสอบ
URL ประเภทข้อผิดพลาดควรชี้ไปที่ใด?
ควรชี้ไปยังเอกสารประกอบที่มนุษย์อ่านได้ซึ่งอธิบายประเภทข้อผิดพลาด สาเหตุที่เป็นไปได้ และวิธีแก้ไข
ฉันจำเป็นต้องเปลี่ยนรหัสสถานะ HTTP เมื่อใช้ RFC 9457 หรือไม่?
ไม่ RFC 9457 ทำงานร่วมกับรหัสสถานะ HTTP มาตรฐาน ฟิลด์ status ในการตอบกลับควรตรงกับรหัสสถานะ HTTP
ฉันจะทดสอบการปฏิบัติตาม RFC 9457 ได้อย่างไร?
ใช้ Apidog เพื่อตรวจสอบโครงสร้างการตอบกลับข้อผิดพลาด, ตรวจสอบฟิลด์ที่จำเป็น, และยืนยันว่าประเภทเนื้อหาตรงตามข้อกำหนดของ RFC 9457