יומן שינויים

במאמר הזה מפורטים שינויים היסטוריים חשובים במדריך לעיצוב API, כמו עדכונים במוסכמות לגבי שמות, בטיפול בשגיאות ובשדות סטנדרטיים. בנוסף, הוא מתעד את המעברים של מסמכי התיעוד אל Google API Improvement Proposals (הצעות לשיפור Google API,‏ AIP).

2025-06

• הפנינו את מוסכמת השמות של דף העיצוב אל Google AIP.

2024-10

• הפנייה אוטומטית של דפי עיצוב אל Google AIPs, למעט מבנה הספרייה ומוסכמות מתן השמות.

2021-12

• המונח Networked API שונה ל-Network API כדי לשמור על עקביות עם https://google.aip.dev/9.

2021-09

• תיעוד של פורמט השגיאות של Google API גרסה 1 וגרסה 2.

2021-04

• השקנו גרסאות שונות של דפים בהתאם להרשאות הגישה.

• הוספנו את המונח API title למילון המונחים.

2021-03

• הוספנו הערה לשדות פלט בלבד.

• צריך לעדכן את ההנחיות לגבי ערכי enum כך שתמיד יכללו ערך _UNSPECIFIED מפורש.

• הוספנו הנחיות לגבי יצירה וניתוח של שמות משאבים.

• הוספת progress_percent לשדות רגילים.

2021-02

• נוספו הנחיות לגבי שדות פרימיטיביים של proto3 optional.

2021-01

• עדכנו את דף השגיאות כדי לכלול את השיפור האחרון שקשור ל-google.rpc.ErrorInfo ול-google.api.ErrorReason.

• הוספנו הנחיות לשימוש ב-oauth2l, ב-curl ובפרמטרים של המערכת כדי לפתור בעיות בשגיאות ב-Google APIs.

• נוספה הסבר על קוד השגיאה 502 לדף השגיאות. זו שגיאת רשת ולא שגיאת API.

2020-12

• שמות החבילות צריכים לכלול שמות רכיבים ביחיד כדי לשמור על עקביות גלובלית. שמות החבילות לא יכולים לכלול קווים תחתונים.

2020-09

• ניקינו כמה דרישות לתיאור שדות, ושינינו כמה מקרים שבהם השתמשנו במילה must (חובה) מחוץ ל-RFC 2119 להוראות should (רצוי) של RFC 2119.

• הוסר השדה הרגיל bool deleted לטובת google.protobuf.Timestamp delete_time (שכבר היה רשום).

2020-07

• עדכון הקובץ documentation.md כך שיתאים לכתובת https://google.aip.dev/192#formatting. אסור להשתמש בטבלאות Markdown וב-HTML גולמי בהערות פרוטו.

• נוסף ErrorInfo לטיפול בשגיאות.

• נוספו מטענים ייעודיים (payloads) גדולים לתבניות עיצוב.

2020-04

• שונה השם Cloud APIs ל-Google Cloud APIs במילון המונחים.
• הוספנו את המונחים API ושירות כמילים נרדפות למונח שירות API.

2020-02

• עדכנו את ניהול הגרסאות כדי להוסיף שתי אסטרטגיות לניהול גרסאות (מבוססות-ערוץ ומבוססות-מהדורה), הסרנו את ההנחיות לגבי גרסאות נקודתיות ושינינו את האופן שבו אנחנו מתייחסים לניהול גרסאות סמנטי.

2020-01

• הוספת שמירת נתונים לדפוסי עיצוב.

2019-11

• הוספת מונחי Cloud APIs למילון.
• מומלץ להציע ללקוחות לנסות שוב רק במקרה של שגיאות UNAVAILABLE.

2019-06

• הוספת 'Bool vs Enum vs String' לתבניות עיצוב.

2019-03

• להוסיף פרמטרים של המערכת לשדות רגילים.

2019-02

• הוספת שמות בהיקף הדומיין לדפוסי עיצוב.

2018-03

• הוספת סמנטיקה של סגירה חלקית של סטרימינג לתבניות עיצוב.

2018-02

• מוסיפים את read_time לשדות רגילים.

2018-01

• הוספת הפניה לסכימה להגדרת שירות API.

2017-12

• הוספנו הבהרה לגבי העובדה שגרסה ראשית של API חייבת להיות הרכיב האחרון בשם חבילת ה-proto.

2017-11

• הסבר למה הפונקציה Create מקבלת משאב קלט.
• הבהרה של מזהי אוספים שאין להם צורת רבים, כמו evidence ו-weather.
• הוספת משאב יחיד לתבניות עיצוב.
• הוספנו הבהרות לגבי מוסכמות למתן שמות ב-C# לראשי תיבות ולגרסאות.

2017-09

• הוספת mime_type לשדות רגילים.
• הוספת expire_time לשדות רגילים.
• הוספת start_time וend_time לשדות סטנדרטיים.

2017-02

• הוספה של 'נקודת קצה ל-API' למילון המונחים.
• הוספת update_mask לשדות רגילים.
• הוספת קישור ל-FieldMask לשיטות רגילות.
• מציינים שמפרט OpenAPI לא תומך במספרים שלמים לא חתומים.
• להבהיר ששמות של שיטות צריכים לכלול פעלים בציווי.