قراردادهای مشترک

این صفحه قاعده‌هایی را می‌آورد که در همه‌ی درخواست‌ها یکسان است. جزئیات هر درخواست در مرجع API آمده است.

نشانی پایه

درخواست‌ها	نشانی پایه
همه‌ی مسیرهای /api/v1/...، /thumbnail/... و /version	دروازه‌ی API گره‌ی کاربر، مثلاً https://apigateway.n2.<domain> (از یافتن گره)
/Selection/Assign/{userId} و درخواست‌های مدیریت گره و مجوز	https://nb.<domain> روی سرور سراسری (اصلی)

همه‌ی درخواست‌ها روی HTTPS هستند و بدنه‌ها JSON است، مگر جایی که مرجع multipart/form-data (بارگذاری) یا فایل (دانلود) را نام برده باشد. دروازه به مسیری که بخشی برابر . یا .. داشته باشد، حتی به شکل رمزگذاری‌شده با %، پاسخ 404 می‌دهد.

سرآیندها

سرآیند	کی لازم است	مقدار
Authorization	همه‌ی درخواست‌ها به‌جز درخواست‌های عمومی	Bearer <access_token> (احراز هویت)
x-container	درخواست‌هایی که در مرجع این سرآیند را دارند	شناسه‌ی فضای کاربر
Content-Type	درخواست‌های دارای بدنه	application/json یا multipart/form-data

گرفتن x-container: پس از ورود، یک بار این درخواست را بفرستید (خودش x-container نمی‌خواهد) و مقدار فیلد container پاسخ را در همه‌ی درخواست‌های بعدی بفرستید:

GET /api/v1/services/current
Authorization: Bearer <access_token>

این مقدار را از ایمیل نسازید. معمولاً شبیه ایمیل است (ali_rezaei_example_com)، ولی اگر نام دیگری همان شکل را گرفته باشد پسوندی مثل _2 دارد. اگر x-container با فضای کاربر یکی نباشد، پاسخ 401 یا 403 است. ناظرها هم فقط با x-container خودشان درخواست می‌دهند.

دسترسی

هر درخواست در مرجع یکی از این سطح‌های دسترسی را دارد:

سطح	معنا
عمومی	بدون توکن. مثلاً دانلود از پیوند اشتراک عمومی.
کاربر واردشده	هر کاربری که توکن معتبر دارد، فقط در فضای خودش. حساب کاربر در اولین ورود ساخته می‌شود و باید فعال باشد.
ناظر	کاربری که مدیر سامانه به او نقش ناظر داده؛ مشترکین را می‌بیند و مدیریت می‌کند.
مدیر سامانه	کاربری با نقش admin؛ همه‌ی کارهای ناظر را هم می‌تواند انجام دهد.

بعضی درخواست‌ها حق READ یا WRITE روی حساب مشترک را هم می‌خواهند؛ حساب‌های عادی هر دو را دارند. حسابی که فقط READ دارد، برای درخواست‌هایی که چیزی را تغییر می‌دهند پاسخ 403 می‌گیرد.

صفحه‌بندی

فهرست‌ها در خود مسیر صفحه‌بندی می‌شوند و دو شیوه دارند. مرجع جای این مقدارها را در مسیر با نام‌های زیر نشان می‌دهد؛ بخش‌های ثابت مسیر، مثل /skip/ و /take/، همان‌طور که هستند فرستاده می‌شوند.

جای مقدار در مسیر	معنا	درخواست‌ها
{page} و {pageSize}	شماره‌ی صفحه از 0 و تعداد ردیف هر صفحه؛ ردیف شروع برابر page × pageSize است	فهرست و جست‌وجوی پوشه‌ها، مرور پوشه‌های اشتراکی عمومی
{offset} و {limit}	تعداد ردیف‌های ردشده و تعداد ردیف پاسخ	تاریخچه‌ی فایل‌ها، فهرست کارها، گزارش تغییرات، فهرست‌ها و گزارش‌های اشتراک‌گذاری

فهرست‌ها و گزارش‌های اشتراک‌گذاری و گزارش تغییرات {limit} را به ۱ تا ۲۰۰ محدود می‌کنند (صفر یا کمتر یعنی ۲۰). بقیه‌ی فهرست‌ها سقفی ندارند؛ مقدار معقولی بفرستید (مثلاً ۵۰). مرجع هر درخواست معنای دقیق و سقف آن را می‌گوید.

کارهای ناهمگام

رونوشت و جابه‌جایی پوشه، فشرده‌سازی، باز کردن فایل فشرده و رمزگذاری یا رمزگشایی پوشه زمان‌بر هستند. سرور درخواست را می‌پذیرد، فوراً پاسخ 201 بدون بدنه می‌دهد و کار را در پس‌زمینه انجام می‌دهد. وضعیت و نتیجه را از فهرست کارها بخوانید:

GET /api/v1/io-audits/status/{status}/skip/{offset}/take/{limit}

مجوز

وقتی مجوز گره اجازه‌ی کاری را نمی‌دهد (مثلاً بارگذاری یا ساختن پیوند اشتراک در حالت محدود)، پاسخ 402 است:

{ "code": "LICENCE_RESTRICTED", "capability": "upload", "state": "..." }

این خطا را به کاربر نشان دهید و دوباره تلاش نکنید؛ موضوع را مدیر سامانه باید حل کند.

شکل خطاها

شکل بدنه‌ی خطا هنوز در همه‌ی بخش‌ها یکسان نیست. همیشه اول کد وضعیت HTTP را بررسی کنید و بدنه را فقط برای پیام بخوانید:

بخش	شکل بدنه
پوشه‌ها، فایل‌ها، اشتراک‌گذاری از مسیرهای /api/v1/...	{ "statusCode": 400, "message": "...", "error": "..." }
مسیرهای /api/v1/IOService/...	{ "error": "..." }
اتصال‌های بیرونی	{ "error": "...", "code": "...", "detail": "..." }
گردش‌کارها	{ "error": "...", "errorCode": "..." } و در 400 فهرست problems
دانلود از پیوند اشتراک (/api/v1/SharingService/...)	{ "message": "..." }، گاهی متن ساده
مجوز	402 با بدنه‌ی بخش مجوز

کدهای رایج:

کد	معنا
400	ورودی نادرست. بسیاری از خطاهای داخلی هم در حال حاضر به شکل 400 برمی‌گردند.
401	توکن نیست، نامعتبر یا منقضی است، یا حساب کاربر فعال نیست.
403	x-container با کاربر یکی نیست یا حق لازم را ندارید.
404	مورد پیدا نشد یا به شما تعلق ندارد.
402	مجوز گره این کار را اجازه نمی‌دهد.
500	خطای پیش‌بینی‌نشده‌ی سرور. چند مورد شناخته‌شده در مرجع ذکر شده است.

نسخه‌بندی

نسخه‌ی API در مسیر است (/api/v1). این مستندات موج اول نسخه‌ی ۱ است و موج‌های بعدی درخواست‌های تازه به آن اضافه می‌کنند. درخواستی که در مرجع نیامده بخشی از API عمومی نیست.