نسخه‌بندی و منسوخ‌شدن
نسخه در مسیر آمده است: /v1. درون یک نسخه، API فقط گسترش می‌یابد:
- اندپوینت‌های تازه، ورودی‌های اختیاری تازه، فیلدهای تازه در پاسخ‌ها؛
- مقدارهای تازه در فیلدهایی که باز (open-ended) مستند شده‌اند (انواع رویداد، دلایل تطبیق، کدهای خطا).
کلاینت‌هایی بنویسید که فیلدهای ناشناخته را نادیده بگیرند و مقدارهای ناشناختهٔ فیلدهای باز را مدیریت کنند. هر تغییر دیگری (حذف یا تغییر نام یک فیلد، یک ورودی اجباری تازه، تغییر معنا) نسخهٔ تازه‌ای است که کنار نسخهٔ قدیمی ارائه می‌شود.
حذف چطور اعلام می‌شود
اندپوینتی که قرار است حذف شود، دست‌کم ۱۲ ماه پیش از توقف کار اعلام می‌شود. از زمان اعلام، پاسخ‌هایش این سرآیندها را دارند:
Deprecation: @1793491200
Sunset: Mon, 01 Nov 2027 00:00:00 GMT
Link: <https://birlesa.com/developers/deprecations#companies-list>; rel="deprecation"; type="text/html"Deprecation(RFC 9745(در زبانه جدید باز می‌شود)): زمان اعلام، بر حسب ثانیهٔ Unix.Sunset(RFC 8594(در زبانه جدید باز می‌شود)): زمان توقف کار.Link: اطلاعیه‌ای که توضیح می‌دهد چه چیزی جای آن را می‌گیرد و چطور به آن منتقل شوید.
سند OpenAPI آن عملیات را deprecated علامت می‌زند. به سازمان‌هایی که کلیدهایشان هنوز آن را فراخوانی می‌کنند، با ایمیل هم خبر داده می‌شود. این سرآیندها را در کلاینتتان ثبت (لاگ) کنید: زودترین هشداری هستند که دریافت می‌کنید.
محتوای ارسالی وب‌هوک‌ها هم از همین قاعده پیروی می‌کند. ساختار آن (id، type، created_at، data) درون /v1 تغییر نمی‌کند؛ ممکن است انواع رویداد تازه‌ای ظاهر شود و هر وب‌هوک فقط انواعی را می‌گیرد که خواسته است.