مواصفة واجهة برمجة التطبيقات

المرجع الكامل لنقاط نهاية REST. للدروس والأمثلة، انظر دليل واجهة برمجة التطبيقات.

كل ما يستطيع عضو المشروع فعله في واجهة الويب متاح هنا — فتطبيقة الصفحة الواحدة (SPA) تستهلك واجهة برمجة التطبيقات نفسها. العمليات التي تتطلّب دور المالك مُعلَّمة بـ (owner)؛ وكل ما عداها يحتاج عضوية المشروع فقط (أو، للقراءات المُعلَّمة بـ (viewer)، أي مستوى وصول).

الأساس

https://eastagiletracker.com/api/v1

يقدّم https://api.eastagiletracker.com/api/v1 واجهة برمجة التطبيقات نفسها. كل الطلبات والاستجابات بصيغة JSON، باستثناء بضع نقاط نهاية لرفع الملفات تقبل multipart.

المصادقة

يُرسِل كل طلب مصادَق عليه مفتاح API عبر أحد:

X-TrackerToken: <key>
Authorization: Bearer <key>

تبدأ مفاتيح المستخدم بـ ea_user_. وتبدأ مفاتيح الوكلاء بـ ea_agent_. انظر دليل واجهة برمجة التطبيقات ← نوعان من المفاتيح.

نقاط النهاية غير المصادَق عليها: /openapi.json، و/docs، ونقاط نهاية /auth/*، وعمليات البحث في البيانات المرجعية (/story_types، و/story_states، و/effort_scales، …). أما /meta فهي مصادَق عليها — أي مفتاح صالح يعمل، لكنها غير محصورة بالمشروع (يصل إليها أيضًا مفتاح وكيل مرتبط بمشروع).

الأدوار

ثلاثة مستويات تتحكّم في نقاط النهاية المحصورة بالمشروع:

المستوى	من يجتاز	العمليات النموذجية
viewer	viewer، member، owner	القراءات (سرد/جلب القصص، والبحث، والتحليلات)
member	member، owner	كل كتابات عناصر العمل (القصص، والمهام، والتعليقات، …)
owner	owner فقط	إعدادات المشروع، وإدارة العضوية، ومفاتيح الوكلاء، والحذف، والاستيراد، وسجل التدقيق

يتلقّى غير العضو 404 unfound_resource (لا 403) على مسارات المشروع، فلا تكون معرّفات المشاريع قابلة للتعداد.

نقاط النهاية ذاتية الوصف

الطريقة	المسار	الوصف
GET	`/openapi.json`	مواصفة OpenAPI 3 الحيّة. غير مصادَق عليها.
GET	`/docs`	واجهة Swagger UI. غير مصادَق عليها.
GET	`/meta`	هوية المستدعي (`auth.kind`/`key_id`/`agent_id`/`project_id`) + رسم انتقالات حالات نوع القصة. مصادَق عليها (أي مفتاح صالح؛ غير محصورة بالمشروع). استدعِها أولًا.

الحساب / الهوية

تتصرّف هذه على المستدعي وتحتاج مفتاحًا صالحًا فقط (بلا دور مشروع).

الطريقة	المسار	الوصف
POST	`/auth/register`	تسجيل حساب جديد
POST	`/auth/login`	تسجيل الدخول، يُعيد رمز جلسة
POST	`/auth/logout`	تسجيل الخروج
POST	`/auth/forgot-password`	طلب بريد إعادة تعيين كلمة المرور
POST	`/auth/reset-password`	استخدام رمز إعادة تعيين لضبط كلمة مرور جديدة
GET	`/auth/verify-email`	توثيق عنوان بريد إلكتروني
POST	`/auth/accept-invite/lookup`	تحويل رمز دعوة ← بريد إلكتروني (غير مصادَق عليها)
POST	`/auth/accept-invite`	قبول دعوة مشروع (بعد المصادقة)
GET	`/me`	الملف الشخصي للمستخدم الحالي
PUT	`/me`	تحديث الملف الشخصي
DELETE	`/me`	حذف الحساب
PUT	`/me/password`	تغيير كلمة المرور
PUT	`/me/settings`	تحديث الإعدادات (السمة، وتفضيلات الإشعارات)
POST	`/me/avatar`	رفع صورة رمزية (multipart)
POST	`/me/api-token/regenerate`	تدوير رمز API الخاص بك — يُبطِل الجلسات/المفاتيح القائمة
GET	`/me/api_keys` · POST `/me/api_keys` · DELETE `/me/api_keys/{id}`	إدارة مفاتيح API للمستخدم (`ea_user_`)
GET	`/me/activity`	نشاطك عبر كل المشاريع
GET	`/me/data-export`	تصدير ذاتي لبياناتك بموجب اللائحة العامة لحماية البيانات (GDPR)
GET	`/me/consent` · POST `/me/consent`	قراءة / تسجيل الموافقة (`{ consent_type, granted }`)
GET	`/legal/pending` · POST `/legal/accept`	مستندات الموافقة بالنقر المعلّقة / تسجيل القبول
POST	`/contact` · POST `/feedback` · POST `/feedback/with-screenshot`	اتصال + تغذية راجعة داخل التطبيق

البيانات المرجعية (غير مصادَق عليها)

عمليات بحث بذرية تُستخدَم عند إنشاء/تقدير القصص. معرّفات مستقرة.

الطريقة	المسار	الوصف
GET	`/story_types`	feature، bug، chore، release (+ `allow_points`)
GET	`/story_states`	unstarted … accepted، rejected
GET	`/effort_scales`	مقاييس التقدير المتاحة
GET	`/effort_scales/{scale_id}/values`	قيم النقاط في مقياس

المشاريع

الطريقة	المسار	الوصف
GET	`/projects`	سرد مشاريعك
POST	`/projects`	إنشاء مشروع
GET	`/projects/{id}`	جلب تفاصيل المشروع `(viewer)`
PUT	`/projects/{id}`	تحديث إعدادات المشروع `(owner)`
DELETE	`/projects/{id}`	حذف مشروع `(owner)`
GET	`/projects/{id}/audit-log`	تدفق نشاط المشروع `(owner)`
GET	`/projects/{id}/events`	تدفق أحداث مقسَّم صفحاتٍ بمؤشّر `(viewer)` — انظر الأحداث

الأعضاء ومفاتيح الوكلاء

الطريقة	المسار	الوصف
GET	`/projects/{id}/memberships`	سرد الأعضاء `(viewer)`
POST	`/projects/{id}/memberships`	دعوة عضو عبر البريد الإلكتروني `(owner)`
PUT	`/projects/{id}/memberships/{mid}`	تحديث الدور `(owner)`
DELETE	`/projects/{id}/memberships/{mid}`	إزالة عضو `(owner)`
GET / POST	`/projects/{id}/agent_keys`	سرد / إصدار مفاتيح الوكلاء `(owner)`
DELETE	`/projects/{id}/agent_keys/{kid}`	إلغاء مفتاح وكيل `(owner)`

القصص

كل كتابات القصص تحتاج دور member.

الطريقة	المسار	الوصف
GET	`/projects/{id}/stories`	سرد القصص (مقسَّم صفحات، قابل للتصفية) `(viewer)`
POST	`/projects/{id}/stories`	إنشاء قصة
GET	`/projects/{id}/stories/{sid}`	جلب قصة واحدة `(viewer)`
PUT	`/projects/{id}/stories/{sid}`	تحديث قصة
DELETE	`/projects/{id}/stories/{sid}`	حذف قصة
POST	`/projects/{id}/stories/{sid}/transitions`	تغيير الحالة مع التحقّق
POST	`/projects/{id}/stories/bulk_transition`	نقل قصص كثيرة (1–100) دفعةً واحدة
POST	`/projects/{id}/stories/bulk-delete`	حذف قصص كثيرة
POST	`/projects/{id}/stories/bulk-duplicate`	تكرار قصص كثيرة
POST	`/projects/{id}/stories/{sid}/duplicate`	تكرار قصة واحدة

الإنشاء (POST …/stories): { "name" (required), "story_type": "feature|bug|chore|release", "description"?, "estimate"?, "current_state"?, "icebox"?, "labels"? }. يقبل labels صيغة ["auth"] أو [{ "name": "auth" }]؛ وتُنشأ التسميات غير المعروفة. القيم الافتراضية: story_type=feature، وcurrent_state=unstarted.

التحديث (PUT …/stories/{sid}): الحقول نفسها، كلها اختيارية، إضافةً إلى "position" (float) و"force_state_change" (bool).

الانتقال (POST …/transitions): { "to": "<state>", "reason"? }. الحقل هو to. يُعيد { story_id, state }. الحركة غير القانونية ← 422 invalid_transition مع details: { from, to, allowed }.

الانتقال الجماعي (POST …/bulk_transition): { "story_ids": [int,…] (1–100), "to": "<state>", "reason"? }. تُحكَم كل قصة على نحوٍ مستقل؛ يُعيد { results: [ { id, status: "ok" } | { id, status: "failed", error } ] }.

الموارد الفرعية للقصة

كلها member. السرد/الجلب على معظمها (viewer).

الطريقة	المسار	الجسم / ملاحظات
GET / POST	`/projects/{id}/stories/{sid}/tasks` · PUT/DELETE `…/tasks/{tid}`	`{ description (or task_desc), complete?, task_order? }`
GET / POST	`/projects/{id}/stories/{sid}/comments` · PUT/DELETE `…/comments/{cid}`	`{ text (or comment_text) }` أو `{ comment_emoji }`
GET / POST	`/projects/{id}/stories/{sid}/blockers` · PUT/DELETE `…/blockers/{bid}`	`{ blocker_desc, resolved? }`
GET / POST	`/projects/{id}/stories/{sid}/links` · DELETE `…/links/{lid}`	`{ url, link_type?, title? }`
GET / POST	`/projects/{id}/stories/{sid}/reviews` · PUT/DELETE `…/reviews/{rid}`	`{ reviewer_id? / reviewer_agent_id?, status, comment? }`
GET / POST	`/projects/{id}/stories/{sid}/owners` · DELETE `…/owners/{mid}` · DELETE `…/owners/agents/{aid}`	`{ member_id? / agent_id? }` — احذف كليهما لإضافة المستدعي
GET / POST	`/projects/{id}/stories/{sid}/followers` · DELETE `…/followers/{mid}` · DELETE `…/followers/agents/{aid}`	`{ member_id? / agent_id? }`
GET / POST	`/projects/{id}/stories/{sid}/labels` · DELETE `…/labels/{lid}`	`{ name }`
GET / POST	`/projects/{id}/stories/{sid}/attachments` (+ `/json`) · DELETE `…/attachments/{aid}`	رفع multipart (≤ 2 غيغابايت لكل ملف)؛ السرد `(viewer)`

التسميات

member للكتابات، و(viewer) للقراءات.

الطريقة	المسار	الوصف
GET / POST	`/projects/{id}/labels`	سرد / إنشاء تسمية
PUT / DELETE	`/projects/{id}/labels/{lid}`	تحديث / حذف تسمية
POST	`/projects/{id}/labels/{lid}/archive`	أرشفة (إخفاء ناعم) تسمية

التكرارات

الطريقة	المسار	الوصف
GET	`/projects/{id}/iterations`	سرد التكرارات `(member)`
POST	`/projects/{id}/iterations`	إنشاء تكرار يدوي `(owner)`
DELETE	`/projects/{id}/iterations/{itid}`	حذف تكرار `(owner)`

البحث، والتحليلات، والمقاييس، والتفضيلات

الطريقة	المسار	الوصف
GET	`/projects/{id}/search?query=…`	بحث بصيغة التصفية `(viewer)` — انظر الدليل
GET	`/projects/{id}/analytics/{overview,iteration,releases,activity,cycle-time,projections}`	تحليلات `(viewer)`. يأخذ تعمّق التكرار `?iteration_id=`
GET	`/projects/{id}/metrics/{velocity,burndown,story-types}`	مقاييس `(viewer)`
GET / PUT	`/projects/{id}/preferences`	تفضيلات لوحتك لهذا المشروع `(member)`

الأحداث

الطريقة	المسار	الوصف
GET	`/projects/{id}/events`	تدفق أحداث مقسَّم صفحاتٍ بمؤشّر `(viewer)`

معاملات الاستعلام: since=<event_id>، وtypes=story.created,story.transitioned,comment.created,…، وlimit=، وcursor=. تتضمّن الاستجابة next_cursor. مرّر آخر event_id رأيته كـ since لاستئناف.

الاستيراد `(owner)`

الطريقة	المسار	الوصف
POST	`/projects/{id}/import` (+ `/json`)	رفع multipart. `source=` ∈ `pivotal`، و`jira`، و`asana`، و`gitlab`، و`shortcut`، و`trello`، و`linear`، و`plane`، و`plane_json`.

WebSocket

wss://eastagiletracker.com/ws/control?token=<key>

للتحكّم التفاعلي عن بُعد بالواجهة ({ "action": "get_state", "id": "req-1" }). ليست قناة بيانات — كل القراءات/الكتابات تمرّ عبر REST. أحادية النسخة فقط؛ لا تُبثّ عبر النسخ المتعددة.

التكافؤ (Idempotency)

تقبل نقاط نهاية الكتابة (POST، وPUT، وDELETE) ترويسة Idempotency-Key. المفتاح نفسه + الجسم نفسه يعيد تشغيل الاستجابة المخزّنة مؤقتًا (نافذة 24 ساعة)؛ والمفتاح نفسه + جسم مختلف يُعيد 409 idempotency_conflict. لا تُطبَّق على GET/HEAD/OPTIONS، أو /auth/*، أو مسارات /attachments. لا تُخزَّن استجابات 5xx أبدًا — تصل إعادة المحاولة إلى المعالِج.

التقسيم إلى صفحات

تقبل نقاط نهاية السرد cursor=<opaque> وlimit=<n≤200>. وعند ضبطهما، تكون الاستجابة { "items": [...], "next_cursor": "<str|null>" }؛ مرّر next_cursor لتصفّح الصفحات. وتُعيد بعض القوائم أيضًا ترويسة X-Tracker-Pagination-Total.

إسقاط الحقول

تقبل نقاط نهاية السرد fields= (مفصولة بفواصل) لإعادة حقول محددة فقط. يُضمَّن story_id دائمًا؛ ويُعيد اسم حقل غير معروف 400 validation_failed مع الأسماء المخالِفة في details.fields.

GET /projects/123/stories?fields=story_id,name,current_state,owners

صيغة الخطأ

لكل خطأ بصيغة JSON code وerror؛ ويضيف بعضها details:

{ "code": "invalid_transition",
  "error": "Cannot move story from `unstarted` to `accepted`",
  "details": { "from": "unstarted", "to": "accepted", "allowed": ["started"] } }

الحالة	`code`	متى
400	`invalid_parameter`	إدخال سيّئ؛ الرسالة في `error`، بلا `details` (معظم التحقّق: فراغ/طول/بايت صفري/بريد إلكتروني)
400	`validation_failed`	خطأ إدخال مهيكَل؛ `details.fields` هو مصفوفة بأسماء الحقول المخالِفة
401	`unauthenticated`	رمز مفقود/غير صالح
403	`unauthorized_operation`	مصادَق عليه لكن الدور غير كافٍ
404	`unfound_resource`	غير موجود — يُعاد أيضًا لغير الأعضاء
409	`conflict`	تعارض في المورد (مثل التكرار)
409	`idempotency_conflict`	أُعيد استخدام `Idempotency-Key` بجسم مختلف
422	`invalid_transition`	حركة حالة غير قانونية؛ يحمل `details` الحقول `{ from, to, allowed }`
500	`internal_error`	عطل في الخادم — رسالة عامة؛ آمن لإعادة المحاولة

details.fields هو مصفوفة JSON بأسماء الحقول (مثل ["to"])، أحيانًا مع مفاتيح إضافية مثل max. لا توجد خريطة حقل←رسالة.

{ "code": "validation_failed", "error": "unknown field(s): foo", "details": { "fields": ["foo"] } }

حدود المعدّل

لكل مفتاح (لكل IP لنقاط النهاية غير المصادَق عليها)، دلو رموز GCRA:

المصادقة — /auth/*: 0.5 طلب/ث، بدفعة 20.
العامة — /contact، و/feedback: 0.2 طلب/ث، بدفعة 10.
الحساسة — إعادة تعيين كلمة المرور: نحو 0.002 طلب/ث، بدفعة 5.

تجاوز الحدّ يُعيد 429 Too Many Requests مع ترويسة Retry-After وجسم نصّي صِرف (لا غلاف خطأ JSON).