سجل تغييرات API لواجهة مُجيب البرمجية

سجل تغييرات API هذا يذكر كل تغيير في واجهة مُجيب البرمجية العامة (/api/v1) منذ إطلاقها، بتاريخه، الأحدث أولًا. لم يتغيّر أي مسار ولا اسم حقل منذ الإطلاق؛ التغييرات كلها في الأخطاء وترويسات حدود الطلبات.

ما الذي تغيّر في واجهة مُجيب البرمجية؟

2026-11-04

• ترويسات حد المفتاح في كل رد ناجح: الترويسات X-RateLimit-Limit وX-RateLimit-Remaining في رد المفتاح الصالح تصف الآن حد المفتاح نفسه، بعد أن كانت قد تصف حد عنوان الشبكة. وتقول X-RateLimit-Reset الآن كم ثانية بقيت حتى تبدأ دقيقة المفتاح من جديد.
• الخطأ 429 من حد عنوان الشبكة يحمل الآن الرمز RATE_LIMITED، كخطأ حد المفتاح، بدل BAD_REQUEST.
• المعرّف بصيغة غير صحيحة في GET /api/v1/contacts/{id} وGET /api/v1/bookings/{id} يعود الآن بالخطأ 404 ورمز NOT_FOUND، كالمعرّف غير الموجود، بدل الخطأ 400.
• التواريخ المستحيلة تُرفض بالخطأ 400: يومٌ لا وجود له في from أو to (مثل 2026-02-31)، أو from بعد to، أو لحظة في since من السنة 0000. كان التاريخ المستحيل يعود بخطأ في الخادم، وكان from بعد to يعيد قائمة فارغة.
• GET /api/v1/bookings/{id} يعود الآن بالخطأ 404 للسجلات التاريخية المستوردة من سجل قديم، كما كانت القائمة تستبعدها من قبل.

2026-10-25

• الخطأ 400 لمعامل غير صالح يحمل الآن في issues أول 20 مشكلة فقط، ومعها issueCount بعدد المشكلات كلها.

2026-10-19

• إطلاق الواجهة البرمجية العامة: الطلبات الخمسة GET /api/v1/me وGET /api/v1/contacts وGET /api/v1/contacts/{id} وGET /api/v1/bookings وGET /api/v1/bookings/{id}.
• مفاتيح API للقراءة فقط تبدأ بـ mjb_live_، بصلاحيتين: contacts.read وbookings.read، تُرسَل في Authorization: Bearer أو X-Api-Key.
• 60 طلبًا في الدقيقة لكل مفتاح، والتقسيم إلى صفحات بالمؤشر nextCursor، وشكل خطأ موحّد { "error": { "code", "message" } }.

هل تحتاج هذه التغييرات إلى تعديل في برنامجي؟

غالبًا لا، إلا إذا كان برنامجك يبني على السلوك القديم في الحالات التالية:

• إذا كنت تعامل الخطأ 400 من طلب العنصر الواحد على أنه «معرّف غير صحيح»، فعامل الخطأ 404 بالطريقة نفسها.
• إذا كنت تفرّق بين خطأ الحد وغيره بالرمز BAD_REQUEST، فابنِ على RATE_LIMITED أو على رمز HTTP 429.
• إذا كنت ترسل from بعد to وتتوقع قائمة فارغة، فصحّح الترتيب، لأن الطلب يُرفض الآن بالخطأ 400.
• إذا كنت تحسب ما بقي من حدك من الترويسات، فهي الآن أرقام مفتاحك، وX-RateLimit-Reset يخبرك متى تبدأ الدقيقة من جديد.

كيف أعرف أن الواجهة تغيّرت؟

يُسجَّل كل تغيير في هذه الصفحة بتاريخه، ويحمل ملف OpenAPI في الحقل info.version تاريخ آخر تغيير. قارن التاريخ الذي بنيت عليه بالتاريخ الحالي، وراجع ما بينهما هنا. وتفاصيل كل رمز خطأ في الأخطاء وحدود الطلبات.

الأسئلة الشائعة

هل يشمل هذا السجل تغييرات لوحة التحكم؟

لا. يشمل الواجهة البرمجية العامة فقط، أي الطلبات التي تبدأ بـ /api/v1. لتغييرات المنتج كله سجل خاص في المرجع.

هل تغيّر مسار /api/v1 منذ الإطلاق؟

لا. ما زالت الطلبات الخمسة نفسها بالمسارات نفسها، وبالحقول نفسها في الردود.

كيف أعرف أن ملف OpenAPI يطابق آخر تغيير؟

الحقل info.version في الملف يحمل تاريخ آخر تغيير في هذا السجل.

صفحات ذات صلة

• ملف OpenAPI لواجهة مُجيب البرمجية
• الأخطاء وحدود الطلبات في واجهة مُجيب البرمجية
• واجهة مُجيب البرمجية (API) لقراءة عملاء واتساب وحجوزاتهم
• سجل التحديثات في مُجيب: ما الجديد في المنتج شهرًا بشهر