الإصدارات والإيقاف

الإصدار جزء من المسار: /v1. وضمن الإصدار الواحد لا تفعل الواجهة البرمجية سوى أن تتوسع:

نقاط نهاية جديدة، ومُدخلات اختيارية جديدة، وحقول جديدة في الاستجابات؛
قيم جديدة في الحقول الموثّقة بأنها مفتوحة القيم (أنواع الأحداث، وأسباب المطابقة، ورموز الأخطاء).

اكتب عملاء يتجاهلون الحقول التي لا يعرفونها ويتعاملون مع القيم غير المعروفة في الحقول المفتوحة القيم. أما ما سوى ذلك (حذف حقل أو إعادة تسميته، أو مُدخل إلزامي جديد، أو تغيّر في المعنى) فهو إصدار جديد، يُقدَّم إلى جانب الإصدار القديم.

كيف يُعلَن عن الإزالة

يُعلَن عن نقطة النهاية التي ستُزال قبل 12 شهرًا على الأقل من توقفها عن العمل. ومنذ الإعلان، تحمل استجاباتها:

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؛ وقد تظهر أنواع أحداث جديدة، ولا يتلقى خطاف الويب إلا الأنواع التي طلبها.