للمطوّرين

سجل تغييرات API

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

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

v1.3.0

الحاليتغيير جذريصدر في

قراءة مرفقات التعليقات، وعنوان الصفحة في كل مورد

صار المرفق داخل التعليق كائناً له معرّف، ومعه مسار يرجع نص الملف المرفق. وكل مورد يحمل الآن عنوان صفحته في فريقي. وتوحّد ما ترجعه حقول *_slug واستجابات الحذف على المعرّف الثابت.

  • أُضيفGET على /lists/{ref}/comments/{comment}/attachments/{id} و/tasks/{ref}/comments/{comment}/attachments/{id}، ونظيريهما المتداخلين تحت /projects/{project}/lists/{list}. ترجع نص ملف مرفق بتعليق، ومعه comment_id وcomment_url. تُقرأ الملفات النصية وحدها حتى 256 كيلوبايت، وما عداها يُرفض بالرمز 422 مع ذكر اسمه. تحتاج comments:read.
  • أُضيفحقل url في المشروع، وقائمة المهام، والمهمة، وموضوع المجلس، والتعليق، والملف، والمجلد، والحدث، ونتيجة البحث: العنوان الكامل للصفحة التي يفتحها الشخص في فريقي. والعضو وحده بلا url.
  • أُضيفwidened في استجابة البحث، حاضر دائماً. يسمّي كل نوع لم يحمل فيه أي سجل كل كلمات البحث، فنتائجه تقريبية.
  • أُضيفرمزا خطأ: unknown_endpoint (404) لمسار لا يطابق أي endpoint، ويعيد المسار في الرسالة، وproject_in_use (409) عند حذف مشروع يغذّيه تكامل موصول.
  • تغيّركل عنصر في attachments داخل التعليق صار كائناً {id, name, content_type, byte_size}، وكان اسم الملف وحده.
  • تغيّرحقول project_slug، وtask_list_slug، وtask_slug، وdiscussion_slug في الاستجابات تحمل المعرّف الثابت، لا الـ slug.
  • تغيّرتصحيح في التوثيق: POST /tasks/{ref}/move المسطّح يستقبل في target_task_list_slug المعرّف الثابت وحده، ويجوز أن تكون القائمة الوجهة في مشروع آخر من الشركة. وكان التوثيق يقول إنه يبقى داخل المشروع نفسه. أما العنوان المتداخل فيبقى داخل مشروعه.
  • تغيّرقائمة مواضيع المجلس ترجع المواضيع المنشورة وحدها، ولا تظهر فيها المسودات.
  • حُذفلم تعد استجابة حذف قائمة المهام، والمهمة، وموضوع المجلس تحمل slug. السجل المحذوف يُسمّى بـ id وحده.

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

  • إن كنت تقرأ attachments على أنها نصوص، فاقرأ name من كل عنصر.
  • إن كنت تعرض قيمة حقل *_slug لإنسان، فهي معرّف ثابت الآن. اعرض title أو name. وتمريرها إلى أي مسار يبقى صالحاً كما هو.
  • إن كنت تقرأ slug من استجابة الحذف، فاقرأ id.
  • لنقل مهمة عبر العنوان المسطّح، أرسل المعرّف الثابت للقائمة الوجهة، لا الـ slug.

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.
  • لقراءة التعليقات، أضف comments:read إلى العمليات المسموحة لمفتاحك. المفاتيح المُصدرة قبل هذا التاريخ لا تحملها.

v1.0.0

صدر في

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

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

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

كيف نُرقّم

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