נקודות מפתח לתכנון חוזי נתונים ב-JSON API

שורה תחתונה: נעלו בחוזה את מעטפת התשובה, פורמט השגיאה, ייצוג המזהים והזמן והסמנטיקה של null מול היעדר לפני שאתם מתווכחים על עימוד ופרטי שמות; תמיד עטפו את הרמה העליונה במעטפת data כדי שעימוד ומזהי מעקב יוכלו להיווסף אחר כך בלי לשבור קוראים קיימים.

אין תשובות סטנדרטיות בתכנון API, אבל יש כמה החלטות "קשות לקחת בחזרה אחרי שנבחרו" שמוטב לחשוב עליהן לפני שכותבים את שורת הקוד הראשונה.

1. לעטוף את התשובה או לא

שלושה סגנונות:

复制// סגנון A: תשובה חשופה
{ "id": 1, "name": "张三" }

// סגנון B: מעטפת data
{ "data": { "id": 1, "name": "张三" } }

// סגנון C: data + מטא-נתונים
{ "data": { "id": 1, "name": "张三" }, "meta": { "requestId": "a1b2" } }

המלצה: השתמשו במעטפת data אחידה גם לרשימות וגם לפרטים, ולעולם אל תהפכו את הרמה העליונה למערך. כך, הוספת עימוד או מזהי מעקב בהמשך לעולם לא שוברת את החוזה.

2. פורמט שגיאה: העתיקו את RFC 9457

המצאת מבנה שגיאה משלכם היא מקור עצום לעלות תיאום. RFC 9457 (שמחליף את RFC 7807) מגדיר application/problem+json:

复制{
  "type": "https://bbdrug.com/problems/insufficient-balance",
  "title": "余额不足",
  "status": 422,
  "detail": "账户余额 12.00 元，本次扣款需要 30.00 元",
  "instance": "/accounts/A1001/payments/p-889",
  "balance": "12.00",
  "required": "30.00"
}

שדות הרחבה (כמו balance / required שלמעלה) מותרים במפרט, והפרונט יכול להשתמש בהם להודעות מדויקות במקום לפרסר את טקסט ה-detail.

3. עימוד: cursor עדיף על offset

复制// עימוד offset
{ "data": [], "page": { "offset": 40, "limit": 20, "total": 137 } }

// עימוד cursor
{ "data": [], "page": { "nextCursor": "eyJpZCI6MTAwfQ", "hasMore": true } }

המלצה: השתמשו בעימוד offset לטבלאות ניהול (הן צריכות קפיצות דף וסכומים), ובעימוד cursor לפידים אינסופיים שמיועדים למשתמשים.

4. מזהים וזמן

4.1 תמיד השתמשו במחרוזות למזהים

הנימוק כוסה במאמר על טיפוסים: בצד של JavaScript, ערכים מעל 2^53 מאבדים דיוק בשקט. גם אם המזהה הנוכחי הוא מספר שלם קטן שעולה אוטומטית, שימוש במחרוזות משאיר מקום למעבר למזהי snowflake בהמשך.

复制{ "id": "1000000000000000001" }

4.2 השתמשו במחרוזות RFC 3339 לזמן

复制{
  "createdAt": "2026-10-30T10:41:45+08:00",
  "updatedAt": "2026-10-30T02:41:45Z"
}

• אל תשתמשו במספרי חותמת זמן במילישניות: קשים לקריאה, והיחידה (שניות/מילישניות) נטעית לעתים קרובות;
• ציינו את אזור הזמן במפורש: או עם Z או עם offset; לעולם אל תשתמשו ב"שעה מקומית בלי אזור זמן";
• תנו שמות אחידים לשדות כמו xxxAt כדי שיהיה ברור במבט חטוף שזה רגע בזמן.

5. null והיעדר

חייבים לבחור אחת ולכתוב אותה בתיעוד:

הבעיה בגישה A היא ש"הושמט" ו"נשלח כ-null" משמעותם שונה ב-PATCH, וקל לפרש לא נכון; הבעיה בגישה B היא ש-JSON.stringify של הפרונט משמיט שדות שערכם undefined, וזה במקרה מתאים לסמנטיקה.

המלצה מעשית:

• השתמשו בגישה A לגופי תשובה (null פירושו בבירור אין ערך, והפרונט לא צריך להבחין בין undefined);
• השתמשו בגישה B לגופי בקשה (במיוחד PATCH), בשילוב Merge Patch או JSON Patch כדי להפוך את הסמנטיקה למפורשת.

6. שמות שדות ומבנה

החזרת [] במקום null עבור מערכים ריקים חשובה מאוד: data.items.map(...) בפרונט לא יקרוס בגלל null.

7. אסטרטגיית אבולוציה

שלושה כללי משמעת:

1. לקוחות חייבים להיות סובלניים לשדות לא מוכרים (אל תסגרו את עצמכם עם additionalProperties: false);
2. ללקוחות חייב להיות ענף fallback לערכי enum לא מוכרים;
3. שמרו שדות deprecated לפחות גרסה major אחת, וסמנו אותם עם Deprecation בכותרות התשובה או בתיעוד.

8. דוגמה מלאה

复制{
  "data": [
    {
      "id": "1001",
      "name": "JSON 权威指南",
      "price": "89.50",
      "tags": ["json", "spec"],
      "publishedAt": "2026-09-01T00:00:00+08:00",
      "author": null
    }
  ],
  "page": { "nextCursor": null, "hasMore": false },
  "meta": { "requestId": "req-7f3a", "tookMs": 12 }
}

התשובה הזו משקפת את כל המוסכמות שלמעלה: מעטפת data, מזהים כמחרוזות, סכומים כמחרוזות, חותמות זמן עם אזור זמן, null שפירושו חסר, מערך ריק, עימוד cursor, ו-meta למידע observability.

9. צ'קליסט

• [ ] הרמה העליונה אינה מערך; השתמשו במעטפת data אחידה;
• [ ] תשובות שגיאה עוקבות אחרי RFC 9457 וכוללות type יציב;
• [ ] צורת העימוד מתאימה לתרחיש העסקי;
• [ ] מזהים הם מחרוזות, והזמן משתמש ב-RFC 3339;
• [ ] הסמנטיקה של null והיעדר כתובה בתיעוד;
• [ ] סגנון השמות אחיד בפרויקט, ו-enums משתמשים במחרוזות באותיות קטנות;
• [ ] ללקוח יש fallback לשדות לא מוכרים ולערכי enum לא מוכרים;
• [ ] שינויים שוברים עוברים דרך גרסאות או מעבר בכתיבה כפולה.

FAQ

איך אתכנן JSON API שניתן לאבולוציה?

עטפו רשימות ופרטים באופן אחיד במעטפת data ולעולם אל תהפכו את הרמה העליונה למערך, כדי שאפשר יהיה להוסיף עימוד ומזהי מעקב בלי לשבור את החוזה. השתמשו במזהים כמחרוזות ובחותמות זמן RFC 3339, וכתבו בתיעוד את הסמנטיקה של null מול היעדר. השאירו שדות חדשים כאופציונליים ועצמאיים סמנטית, ותנו ללקוחות fallback לשדות ולאומי enum לא מוכרים.

למה לא להמציא פורמט שגיאה מותאם?

המצאת מבנה שגיאה משלכם היא מקור עצום לעלות תיאום. העתיקו את application/problem+json של RFC 9457, זהו בעיות עם type יציב, והתירו שדות הרחבה כמו balance ו-required, כדי שהפרונט יוכל לבנות הודעות מדויקות בלי לפרסר את טקסט ה-detail.

האם כל endpoint צריך להשתמש בעימוד cursor?

לא. טבלאות ניהול צריכות קפיצות דף וסכומים, ולכן עימוד offset מתאים יותר; פידים אינסופיים שמיועדים למשתמשים צריכים להשתמש בעימוד cursor, שנשאר יציב בדפים עמוקים ונמנע מכפילויות או פערים כשהנתונים משתנים. בחרו לפי האם התרחיש צריך קפיצות דף וסכומים.