עיצוב חוזה API לשילוב מערכות משפטיות

עצב חוזה API. ההנחה: הצד השני לא יוכל לשנות את המימוש שלו אחרי שהחוזה ייחתם.

מטרת השילוב: [תאר] מי הצרכן: [מערכת פנימית / לקוח / ספק] אילוצים: [אימות, רשת, רגולציה]

הפק מפרט OpenAPI חלקי הכולל:

1. נקודות קצה — נתיב, פועל, ותיאור מטרה. משאבים בלשון רבים, פעולות דרך הפועל ולא דרך הנתיב.
2. סכמות בקשה ותשובה — כל שדה עם טיפוס, חובה או רשות, ודוגמה. אל תשאיר שדה ללא תיאור.
3. שגיאות — לכל נקודת קצה, כל קוד שגיאה אפשרי עם גוף תשובה מובנה: קוד שגיאה יציב, הודעה לאדם, ושדה שמצביע על מה לתקן. לעולם לא מחרוזת חופשית בלבד.
4. אידמפוטנטיות — לכל פעולה שכותבת, כיצד מונעים כפילות בעת retry. מפתח אידמפוטנטיות, חלון תוקף, והתנהגות בקריאה חוזרת.
5. עימוד וסינון — סמן המשך ולא offset. הסבר מדוע offset נשבר תחת כתיבה מקבילה.
6. גרסאות — כיצד מוסיפים שדה בלי לשבור צרכנים, ומה נחשב שינוי שובר. הגדר מדיניות הפסקת תמיכה.
7. אימות והרשאה — מנגנון, אורך חיי אסימון, וכיצד מבטלים גישה מיידית.
8. מגבלות — rate limit, גודל גוף מקסימלי, timeout, והתנהגות בחריגה.

לבסוף: שלושה שינויים עתידיים סבירים, וכיצד החוזה מאפשר אותם בלי לשבור.