איזה מבנה צריכה תגובת API

שורה תחתונה: בטאו תוצאות עם קודי סטטוס 4xx/5xx, נשאו את ה-payload ב-{ "data": ..., "meta": ... }, ועברו ל-envelope של error בכישלון; זה מספיק ל-API פנימיים, ורק פלטפורמות ציבוריות עם הרבה אינטגרטורים צריכות JSON:API או OpenAPI.

שללו קודם את האפשרות הגרועה ביותר: תמיד להחזיר 200 עם התוצאה בשדה code.

שלוש צורות

A. אובייקט חשוף

复制{ "id": 1, "name": "demo", "price": 99 }

נקי, וסמנטיקת HTTP עושה את העבודה (404 הוא 404). אבל ברגע שצריך pagination, אזהרות או trace id, אין איפה לשים אותם בלי לשנות את החוזה.

B. Envelope יציב

复制{
  "data": { "id": 1, "name": "demo" },
  "meta": { "requestId": "abc", "took": 12 }
}

ה-payload וה-metadata חיים בנפרד, כך ש-metadata חדש לעולם לא מעצב מחדש את data. עולה רמת קינון אחת.

C. הכל envelope (להימנע)

复制{ "code": 0, "message": "success", "data": {...} }

הצורה היא לא החטא; הנוהג הוא. סטטוס 200 לכל תוצאה אומר ש-CDNs, gateways, circuit breakers, מדיניות ניסיון חוזר ודשבורדים כולם רואים הצלחה. כל התראה אז צריכה פירוס מותאם.

ההמלצה

סטטוס HTTP לתוצאה, envelope ל-payload.

复制{
  "data": { "id": 1, "name": "demo" },
  "meta": { "requestId": "req_8f2a", "took": 12 }
}

复制{
  "error": {
    "code": "ORDER_NOT_FOUND",
    "message": "Order does not exist or was deleted",
    "details": [{ "field": "id", "issue": "not_found" }]
  },
  "meta": { "requestId": "req_8f2a" }
}

סטטוס 4xx או 5xx; code יציב וקריא למכונה; message לבני אדם; details לשגיאות טופס ברמת שדה.

כללים קשיחים

1. נקודות קצה של רשימות חייבות לשאת metadata של pagination. בלי total או cursor אין pager.
2. רשימות ריקות מחזירות [], לעולם לא null. null.map הוא תקלה חוזרת.
3. חותמות זמן ב-ISO 8601 עם offset. ראו איזה פורמט לחותמות זמן.
4. מוסכמת שמות אחת. snake_case או camelCase, מומרת פעם אחת בגבול.
5. כסף כיחידות משנה שלמות או כמחרוזות. 99.99 לא מדויק בנקודה צפה בינארית.
6. אל תערבבו null עם היעדר. ראו null או השמטת השדה.

מתי לאמץ מפרט

• פלטפורמות ציבוריות עם הרבה אינטגרטורים: JSON:API או OpenAPI ועוד envelope משותף
• API פנימיים של צוות אחד: ה-envelope שלעיל מספיק
• חוזים חזקים: Schema קודם, מבנים שנוצרים ממנו

מפרטים חוסכים דיון ועלות הצטרפות. לצוות של חמישה אנשים, JSON:API הוא בדרך כלל עבודה שלילית.

שאלות ותשובות

איך לבחור בין אובייקט חשוף ל-envelope?

השתמשו ב-envelope כשצריך pagination, אזהרות או requestId, כך ש-meta יכול לגדול בלי לעצב מחדש את data. החזירו את האובייקט החשוף רק כשאין צורך ב-metadata ואפשר לקבל שהוספת שדות אחר כך משנה את החוזה.

למה API לא צריך להחזיר 200 לכל תוצאה?

CDNs, gateways, circuit breakers, מדיניות ניסיון חוזר ודשבורדים כולם קוראים את סטטוס ה-HTTP כדי להחליט אם לשמור במטמון, לנסות שוב או להתריע. עם 200 בכל מקום הם מתייחסים לכשלים כהצלחות, וכל התראה צריכה פירוס מותאם של הקוד העסקי.

האם נקודות קצה של רשימות צריכות לשאת metadata של pagination?

כן. בלי total או cursor אין pager, ורשימות ריקות חייבות להחזיר [] ולא null, אחרת קריאת .map של הפרונט נשברת.

קריאה נוספת

• null או השמטת השדה
• איזה פורמט לחותמות זמן