סימוכין מלא לנקודות הקצה של REST. למדריכים ולדוגמאות, ראו את מדריך API.
כל מה שחבר בפרויקט יכול לעשות בממשק האינטרנט זמין כאן — ה-SPA צורך את אותו ה-API הזה. פעולות הדורשות את תפקיד ה-owner מסומנות ב-(owner); כל השאר דורש רק חברוּת בפרויקט (או, עבור קריאות המסומנות ב-(viewer), כל רמת גישה).
https://eastagiletracker.com/api/v1https://api.eastagiletracker.com/api/v1 מגיש את אותו ה-API בדיוק. כל הבקשות והתגובות הן JSON, מלבד כמה נקודות קצה של העלאת-קבצים שמקבלות multipart.
כל בקשה מאומתת שולחת מפתח API באמצעות אחד מ:
X-TrackerToken: <key>Authorization: Bearer <key>
מפתחות משתמש מתחילים ב-ea_user_. מפתחות סוכן מתחילים ב-ea_agent_. ראו מדריך API ← שני סוגי מפתחות.
נקודות קצה ללא אימות: /openapi.json, /docs, נקודות הקצה /auth/*, וחיפושי נתוני-הסימוכין (/story_types, /story_states, /effort_scales, …). /meta הוא מאומת — כל מפתח תקף עובד, אך הוא אינו בהיקף פרויקט (מפתח סוכן הקשור לפרויקט מגיע אליו גם הוא).
תפקידים
Section titled “תפקידים”שלוש רמות מהוות שער לנקודות קצה בהיקף פרויקט:
| רמה | מי עובר | פעולות טיפוסיות |
|---|---|---|
| viewer | viewer, member, owner | קריאות (רשימה/קבלת סיפורים, חיפוש, אנליטיקה) |
| member | member, owner | כל כתיבות פריטי-העבודה (סיפורים, מטלות, תגובות, …) |
| owner | owner בלבד | הגדרות פרויקט, ניהול חברוּת, מפתחות סוכן, מחיקה, ייבוא, שובל ביקורת |
לא-חבר מקבל 404 unfound_resource (לא 403) בנתיבי פרויקט, כך שמזהי פרויקט אינם ניתנים למניין.
נקודות קצה מתארות-עצמן
Section titled “נקודות קצה מתארות-עצמן”| שיטה | נתיב | תיאור |
|---|---|---|
| GET | /openapi.json | מפרט OpenAPI 3 החי. ללא אימות. |
| GET | /docs | Swagger UI. ללא אימות. |
| GET | /meta | זהות הקורא (auth.kind/key_id/agent_id/project_id) + גרף המעברים לכל-סוג-סיפור. מאומת (כל מפתח תקף; לא בהיקף פרויקט). קראו לזה תחילה. |
חשבון / זהות
Section titled “חשבון / זהות”אלה פועלים על הקורא ודורשים רק מפתח תקף (ללא תפקיד פרויקט).
| שיטה | נתיב | תיאור |
|---|---|---|
| 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 | מסמכי clickwrap ממתינים / רישום קבלה |
| POST | /contact · POST /feedback · POST /feedback/with-screenshot | יצירת קשר + משוב בתוך האפליקציה |
נתוני סימוכין (ללא אימות)
Section titled “נתוני סימוכין (ללא אימות)”חיפושי seed המשמשים ביצירת/הערכת סיפורים. מזהים יציבים.
| שיטה | נתיב | תיאור |
|---|---|---|
| GET | /story_types | feature, bug, chore, release (+ allow_points) |
| GET | /story_states | unstarted … accepted, rejected |
| GET | /effort_scales | סולמות הערכה זמינים |
| GET | /effort_scales/{scale_id}/values | ערכי הנקודות בסולם |
פרויקטים
Section titled “פרויקטים”| שיטה | נתיב | תיאור |
|---|---|---|
| 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 | זרם אירועים מדופדף-cursor (viewer) — ראו Events |
חברים ומפתחות סוכן
Section titled “חברים ומפתחות סוכן”| שיטה | נתיב | תיאור |
|---|---|---|
| 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) |
סיפורים
Section titled “סיפורים”כל כתיבות הסיפור דורשות את תפקיד ה-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" (חובה), "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 } ] }.
תת-משאבים של סיפור
Section titled “תת-משאבים של סיפור”כולם member. רשימה/GET על רובם הוא (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 GB כל אחד); רשימה היא (viewer) |
תוויות
Section titled “תוויות”member לכתיבות, (viewer) לקריאות.
| שיטה | נתיב | תיאור |
|---|---|---|
| GET / POST | /projects/{id}/labels | רשימה / יצירת תווית |
| PUT / DELETE | /projects/{id}/labels/{lid} | עדכון / מחיקת תווית |
| POST | /projects/{id}/labels/{lid}/archive | ארכוב (הסתרה רכה) של תווית |
איטרציות
Section titled “איטרציות”| שיטה | נתיב | תיאור |
|---|---|---|
| GET | /projects/{id}/iterations | רשימת איטרציות (member) |
| POST | /projects/{id}/iterations | יצירת איטרציה ידנית (owner) |
| DELETE | /projects/{id}/iterations/{itid} | מחיקת איטרציה (owner) |
חיפוש, אנליטיקה, מדדים, העדפות
Section titled “חיפוש, אנליטיקה, מדדים, העדפות”| שיטה | נתיב | תיאור |
|---|---|---|
| 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) |
אירועים
Section titled “אירועים”| שיטה | נתיב | תיאור |
|---|---|---|
| GET | /projects/{id}/events | זרם אירועים מדופדף-cursor (viewer) |
פרמטרי שאילתה: since=<event_id>, types=story.created,story.transitioned,comment.created,…, limit=, cursor=. התגובה כוללת next_cursor. העבירו את ה-event_id האחרון שראיתם כ-since כדי להמשיך.
ייבוא (owner)
Section titled “ייבוא (owner)”| שיטה | נתיב | תיאור |
|---|---|---|
| POST | /projects/{id}/import (+ /json) | העלאת multipart. source= ∈ pivotal, jira, asana, gitlab, shortcut, trello, linear, plane, plane_json. |
WebSocket
Section titled “WebSocket”wss://eastagiletracker.com/ws/control?token=<key>לשליטה מרחוק אינטראקטיבית בממשק המשתמש ({ "action": "get_state", "id": "req-1" }). אינו ערוץ נתונים — כל הקריאות/הכתיבות עוברות דרך REST. מופע יחיד בלבד; אינו מתפרס על פני רפליקות.
אידמפוטנטיות
Section titled “אידמפוטנטיות”נקודות קצה של כתיבה (POST, PUT, DELETE) מקבלות כותרת Idempotency-Key. אותו מפתח + אותו גוף משמיע מחדש את התגובה השמורה (חלון של 24 שעות); אותו מפתח + גוף שונה מחזיר 409 idempotency_conflict. אינו חל על GET/HEAD/OPTIONS, /auth/*, או נתיבי /attachments. תגובות 5xx לעולם אינן נשמרות — ניסיון חוזר מגיע ל-handler.
דפדוף (Pagination)
Section titled “דפדוף (Pagination)”נקודות קצה של רשימה מקבלות cursor=<opaque> ו-limit=<n≤200>. כשהוגדר, התגובה היא { "items": [...], "next_cursor": "<str|null>" }; העבירו את next_cursor בחזרה כדי לדפדף. חלק מהרשימות גם מחזירות כותרת X-Tracker-Pagination-Total.
הקרנת שדות (Field projection)
Section titled “הקרנת שדות (Field projection)”נקודות קצה של רשימה מקבלות fields= (מופרד בפסיקים) כדי להחזיר רק שדות מסוימים. story_id תמיד נכלל; שם שדה לא-מוכר מחזיר 400 validation_failed עם השמות הפוגעים ב-details.fields.
GET /projects/123/stories?fields=story_id,name,current_state,ownersפורמט שגיאה
Section titled “פורמט שגיאה”לכל שגיאת 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 (רוב האימות: ריק/אורך/null-byte/דוא”ל) |
| 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"] } }מגבלות קצב
Section titled “מגבלות קצב”לכל-מפתח (לכל-IP עבור נקודות קצה ללא אימות), דלי אסימונים GCRA:
- Auth —
/auth/*: 0.5 בקשות/שנייה, פרץ 20. - Public —
/contact,/feedback: 0.2 בקשות/שנייה, פרץ 10. - רגיש — איפוס-סיסמה: ~0.002 בקשות/שנייה, פרץ 5.
מגבלה שנחרגה מחזירה 429 Too Many Requests עם כותרת Retry-After וגוף טקסט-רגיל (לא מעטפת שגיאת ה-JSON).