قراردادها

پوشش پاسخ، صفحه‌بندی، نوع محتوا و شناسه‌ها — چیزهایی که در همهٔ مسیرها یکسان‌اند.

چهار چیز دربارهٔ همهٔ مسیرهای این مرجع درست است. یک‌بار خواندنشان اینجا، از تکرارشان در هر صفحه جلوگیری می‌کند.

پوشش پاسخ

پاسخ‌های موفق همیشه HTTP ۲۰۰ هستند با پوششی دوکلیدی. داده‌ای که می‌خواهید زیر data است — حتی برای ساخت هم هیچ‌وقت ۲۰۱ برنمی‌گردد.

پاسخ

{
  "status": "ok",
  "data": {
    "id": "8f14e45f-ceea-467a-9f4c-1a2b3c4d5e6f",
    "title": "Cardiology intake",
    "description": "Patient handbooks and discharge protocols",
    "share_token": "s7Kd0pLm2Qx",
    "created_at": "2026-08-05T09:14:22.118Z",
    "updated_at": "2026-08-05T09:14:22.118Z"
  }
}

خطاها استثنای قاعدهٔ ۲۰۰ هستند: کد وضعیت واقعی دارند. بسته به این‌که کدام لایه درخواست را رد کرده، دو شکل بدنه وجود دارد و کلاینت باید هر دو را بخواند.

404

{
  "status": "failed",
  "message": "Workspace not found"
}

چون موفقیت همیشه ۲۰۰ است، برای تشخیص موفق بودن یک create روی کد وضعیت شرط نگذارید. روی <code>res.ok</code> شرط بگذارید و بعد <code>data</code> را بخوانید.

صفحه‌بندی

مسیرهای فهرست صفحه‌بندی می‌شوند. شیء صفحه داخل data قرار دارد و next یک نشانی کامل است که مستقیم دنبالش می‌روید، نه نشانگری که باید خودتان بسازید.

پاسخ

{
  "status": "ok",
  "data": {
    "count": 2,
    "next": null,
    "previous": null,
    "results": [
      {
        "id": "8f14e45f-ceea-467a-9f4c-1a2b3c4d5e6f",
        "title": "Cardiology intake",
        "description": "Patient handbooks and discharge protocols",
        "share_token": "s7Kd0pLm2Qx",
        "created_at": "2026-08-05T09:14:22.118Z",
        "updated_at": "2026-08-05T09:14:22.118Z"
      }
    ]
  }
}

دو پارامتر کوئری کنترلش می‌کنند. سقف page_size برابر ۲۰۰ است — درخواست عدد بزرگ‌تر بی‌سروصدا ۲۰۰ می‌دهد، نه خطا.

فیلد	نوع	توضیح
`page`	`integer`	شمارهٔ صفحه، از ۱ شروع می‌شود. پیش‌فرض ۱ است.
`page_size`	`integer`	تعداد نتیجه در هر صفحه. پیش‌فرض ۳۰ و حداکثر ۲۰۰.

یک مسیر این شکل را می‌شکند: در API کنسول، بخش‌های یک سند تصویری به‌جای شیء صفحه‌بندی، آرایه‌ای ساده برمی‌گردانند. جزو این مرجع نیست، اما اگر روزی صدایش زدید، هر دو حالت را مدیریت کنید.

نوع محتوا

بیشتر مسیرها JSON می‌پذیرند. دو تا نمی‌پذیرند و همین مهم است:

بارگذاری سند فقط multipart/form-data است. بدنهٔ JSON آنجا خطای 415 می‌گیرد، هرچند مسیر یک create معمولی است.
فرستادن پیام گفت‌وگو هم JSON می‌پذیرد و هم multipart. وقتی تصویر پیوست می‌کنید multipart بفرستید، در بقیهٔ موارد JSON.

وقتی multipart می‌فرستید، هرگز هدر Content-Type را خودتان تنظیم نکنید. این هدر باید یک boundary داشته باشد که کلاینت HTTP برای هر درخواست می‌سازد، و اگر خودتان بنویسیدش آن را بازنویسی می‌کنید — سرور آن‌وقت هیچ فیلدی را نمی‌خواند و خطای اعتبارسنجی می‌گیرید که شبیه اشتباه در نام فیلد به نظر می‌رسد.

شناسه‌ها و اسلش پایانی

همهٔ شناسه‌ها UUID هستند. شناسهٔ فضای کاری و سند در مسیرها می‌آیند؛ external_user_id تنها شناسه‌ای است که خودتان انتخاب می‌کنید و یک رشتهٔ دلخواه تا ۲۵۵ کاراکتر است.

همهٔ مسیرها به اسلش ختم می‌شوند. سرور برای شکل بدون اسلش تغییر مسیر می‌فرستد و POST پس از تغییر مسیر به GET بدون بدنه تبدیل می‌شود — یعنی درخواست ظاهراً موفق می‌شود و بی‌سروصدا هیچ کاری نمی‌کند.

{ "status": "ok", "data": { "id": "8f14e45f-ceea-467a-9f4c-1a2b3c4d5e6f", "title": "Cardiology intake", "description": "Patient handbooks and discharge protocols", "share_token": "s7Kd0pLm2Qx", "created_at": "2026-08-05T09:14:22.118Z", "updated_at": "2026-08-05T09:14:22.118Z" } }

{ "status": "ok", "data": { "count": 2, "next": null, "previous": null, "results": [ { "id": "8f14e45f-ceea-467a-9f4c-1a2b3c4d5e6f", "title": "Cardiology intake", "description": "Patient handbooks and discharge protocols", "share_token": "s7Kd0pLm2Qx", "created_at": "2026-08-05T09:14:22.118Z", "updated_at": "2026-08-05T09:14:22.118Z" } ] } }

page

integer

شمارهٔ صفحه، از ۱ شروع می‌شود. پیش‌فرض ۱ است.

page_size

integer

تعداد نتیجه در هر صفحه. پیش‌فرض ۳۰ و حداکثر ۲۰۰.

نوع محتوا

بیشتر مسیرها JSON می‌پذیرند. دو تا نمی‌پذیرند و همین مهم است:

بارگذاری سند فقط multipart/form-data است. بدنهٔ JSON آنجا خطای 415 می‌گیرد، هرچند مسیر یک create معمولی است.

فرستادن پیام گفت‌وگو هم JSON می‌پذیرد و هم multipart. وقتی تصویر پیوست می‌کنید multipart بفرستید، در بقیهٔ موارد JSON.

شناسه‌ها و اسلش پایانی