نسخه‌های API
نسخهٔ ۱
Section titled “نسخهٔ ۱”API لُب در نسخهٔ ۱ است. همهٔ مسیرها با /api/v1 شروع می‌شوند، و هر پاسخ JSON که مسیری از
مرجع API به درخواستی موفق می‌دهد schemaVersion: 1 را دارد.
درون v1، تغییرها فقط اضافه می‌کنند
Section titled “درون v1، تغییرها فقط اضافه می‌کنند”هر تغییر درون v1 چیزی اضافه می‌کند و چیزی را برنمی‌دارد:
- مسیرهای تازه؛
- فیلدهای اختیاری تازه در درخواست؛
- فیلدهای تازه در پاسخ؛
- مقدارهای تازه در فیلدی که توضیحش می‌گوید ممکن است مقدارهای دیگری هم بگیرد، مثل
owner.typeدرGET /whoami.
هیچ چیزی حذف نمی‌شود یا تغییر نام نمی‌دهد، و schemaVersion همان 1 می‌ماند.
پس برنامهٔ شما باید آنچه را نمی‌شناسد نادیده بگیرد. فیلدی که نمی‌شناسد ممکن است هر جای پاسخ بیاید: از آن بگذرد و هرگز به خاطرش خطا ندهد. با انعطاف بخوانید همین را برای جلسهٔ کامل نشان می‌دهد.
تغییری که سازگاری را بشکند، نسخهٔ تازه است
Section titled “تغییری که سازگاری را بشکند، نسخهٔ تازه است”تغییری که چیزی بیش از افزودن باشد، فقط به‌صورت نسخهٔ تازه‌ای از API می‌آید، در /api/v2.
تغییرها کجا اعلام می‌شوند
Section titled “تغییرها کجا اعلام می‌شوند”تغییرها در تغییرات اعلام می‌شوند.