للمطوّرين

سجل تغييرات API

كل إصدار وما حمله. المواصفة تصف الواجهة كما هي اليوم ولا تتذكر ما كانت عليه، وهذه الصفحة هي تلك الذاكرة.

الإصدار الحالي v1.2.0

v1.2.0

الحاليصدر في

الوقت المستغرق على المهمة، كتابةً وقراءةً

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

  • أُضيفPOST /tasks/{ref}/time وPOST /projects/{project}/lists/{list}/tasks/{task}/time: تسجّل المدة بإحدى ثلاث صيغ تعني جميعها تسعين دقيقة، "1:30" و"1.5" بالساعات العشرية و"90" بالدقائق، والسلسلة الفارغة تمسح الحقل. القيمة تحلّ محلّ السابقة ولا تُضاف إليها، و"0" مرفوضة لأن من يرسلها يقصد المسح غالباً. تحتاج tasks:write وخطة تحمل تتبّع الوقت، وإلا 403 بلا تسجيل.
  • أُضيفtime_spent_minutes في كل استجابة مهمة، حاضر دائماً وnull حين لم يقس أحد. وnull ليست صفراً: الأولى تعني أن أحداً لم يقل كم استغرقت، والثانية تعني أنها لم تستغرق شيئاً. القراءة لا تشترط خطة، لأن الأرقام سجل العميل عن عمله.

v1.1.0

تغيير جذريصدر في

عنوان مسطّح لكل سجل، وقراءة للتعليقات

صار لكل سجل عنوان ثانٍ قصير يكفي وحده، بلا سلسلة الآباء التي كانت تسبقه. ومعه كسبت comments نصفها القارئ، وتغيّر مقطع قوائم المهام في المسار.

  • تغيّرمقطع قوائم المهام في المسار صار lists بدل task-lists، في المسارات المتداخلة كلها: /projects/{project}/lists و/projects/{project}/lists/{list}/tasks وما تفرّع عنهما.
  • تغيّرحقل id في الاستجابة صار المعرّف الثابت: prj-8f3kd للمشروع، وlst-4m2qp للقائمة، وtsk-9wb7t للمهمة، وmjl-6khz2 لموضوع المجلس. وكان الـ slug.
  • أُضيفعنوان مسطّح لكل سجل يحمل معرّفاً ثابتاً: GET/PATCH/DELETE على /lists/{ref} و/tasks/{ref} و/discussions/{ref}، وDELETE /files/{ref}، ومعها complete وincomplete وmove. لا يستقبل هذا العنوان الـ slug، لأن الـ slug يتكرر بين المشاريع.
  • أُضيفمجموعة تحت أب مسطّح: GET/POST /lists/{ref}/tasks و/lists/{ref}/comments و/tasks/{ref}/comments. المجموعة تبقى تحت أبيها، لكن الأب يُسمّى بمعرّفه وحده.
  • أُضيفعملية comments:read، ومعها GET على تعليقات قائمة المهام وتعليقات المهمة، مرتّبةً من الأقدم إلى الأحدث ومقسّمةً إلى صفحات. كانت comments المجموعة الوحيدة التي تكتب ولا تقرأ.
  • أُضيفحقلان في التعليق: updated_at، ويساوي created_at حتى يُعدَّل التعليق، وattachments، وهو أسماء الملفات المضمّنة في المتن التي يُسقطها النص العادي.
  • تغيّرنتائج البحث ترجع المعرّف الثابت في id، ومعه مفاتيح *_slug كما كانت. والمجلد وحده بلا id، فمعرّفه الرقمي هو كل ما تستقبله مساراته.
  • حُذفلم يعد /projects/{project}/task-lists وما تفرّع عنه يُحلّ. المقطع الجديد lists.

ما على تكاملك أن يفعله

  • استبدل task-lists بـ lists في كل مسار تبنيه. هذا هو التغيير الوحيد الذي يوقف تكاملاً قائماً.
  • الـ slug ما زال مقبولاً في كل موضع كان يُقبل فيه، والمعرّف الرقمي للملف كذلك، فما خزّنته لا يحتاج ترحيلاً. الجديد أنك تستقبل معرّفاً ثابتاً بدله.
  • إن كنت تعرض id لمستخدم على أنه عنوان مقروء، فهو الآن معرّف ثابت لا اسم. اعرض title أو name، أو مفتاح *_slug من نتيجة البحث.
  • لقراءة التعليقات، أضف comments:read إلى العمليات المسموحة لمفتاحك. المفاتيح المُصدرة قبل هذا التاريخ لا تحملها.

v1.0.0

صدر في

الإصدار الأول

أول إصدار عام للواجهة، في مرحلة معاينة تُفعَّل لكل شركة على حدة.

  • أُضيفالمشاريع، وقوائم المهام، والمهام، ومواضيع المجلس، والتعليقات، والملفات، والمجلدات، وأحداث التقويم، والأعضاء، والبحث الموحّد، وهوية المفتاح.
  • أُضيفمصادقة بمفتاح Bearer، وبوابتان: النطاق سقفاً، وقائمة العمليات المسموحة بوابةً فعلية. وعمليات الحذف خارج المنح الافتراضي.
  • أُضيفأشكال استجابة موحّدة، وترقيم صفحات، وحصة يومية لكل شركة مع headers تُضاف إلى كل استجابة مخدومة.

كيف نُرقّم

الرقم هنا هو إصدار العقد الذي تصفه هذه الوثائق، وهو غير الـ v1 في عنوان الخدمة، فذاك إصدار المسار ولا يتحرك إلا حين يقوم سطح جديد بجانب القديم. والواجهة في مرحلة معاينة، فكل تحديث يرفع الرقم الأوسط، ويبقى الأول محجوزاً لما بعد الإتاحة العامة. وكل إصدار هنا يطابق info.version في ملف OpenAPI، وفحص في البناء يمنع الاثنين من الافتراق.