نام پروتکل سرور

پروتکل مورد استفاده توسط جامی برای جستجو و ثبت نام نام بر اساس HTTP [REST] (https://en.wikipedia.org/wiki/Representational_state_transfer) API پاسخ به درخواست ها با اسناد JSON و کد های وضعیت HTTP منظم است.

نام سرور عمومی در ns.jami.net میزبانی شده و از یک بلاکچین به عنوان پس زمینه استفاده می کند. پیاده سازی دیگری می تواند از هر پایگاه داده یا خدمات دایرکتوری دیگری استفاده کند که پروتکل نام سرور را قابل استفاده مجدد می کند.

اگر نام سرور خود را اجرا کنید، جستجوی یک نام کاربری به صورت username@example.com نام username را با نام سرور در example.com جستجو می کند. (برای استفاده از نام سرور پیش فرض نیازی به اضافه کردن @ns.jami.net نیست.)

قوانین فرمت نام

نام های کاربر توسط یک regex بررسی می شوند تا برخی از قوانین مربوط به فرمت آنها را تضمین کنند:

  • طول باید بین 3 تا 32 حرف باشد

  • Those characters must be alphanumerical with dashes - being also accepted.

سوال کردن اسم

این سرویس اصلی توسط یک سرور نام ارائه شده است. این امکان را برای دریافت هویت Jami که به یک نام کاربر مربوط است.

درخواست

یک درخواست برای نام foobar یک درخواست GET است که /name/foobar به عنوان URI.

پاسخ (موفقیت)

اگر نام پیدا شود، پاسخ با کد وضعیت 200 OK باید به مشتری با یک فیلدی Content-type به عنوان application/json ارسال شود.

این سند یک سند JSON با دو صف است: name و addr. name برابر با درخواست شده است و addr یک نمایش شش اعشاری از ID Jami با پیشگویی 0x است.

در مثال ما، پاسخ JSON این است:

{
    "name":"foobar",
    "addr":"0x29347542eb07159f316577e1ae16243d152f6b7b"
}

پاسخ (نابودی)

اگر نام پیدا نشود، پاسخ با کد وضعیت 404 Not Found باید به مشتری با یک فیلدی Content-type به عنوان application/json ارسال شود.

این جسم یک سند JSON با یک صف است: error. این ویژگی با یک پیام خطا پر شده است که خطا را توضیح می دهد (و ممکن است در آینده در مشتری نمایش داده شود).

در مورد اجرای مرجع، سند بازگردانده شده عبارت است از:

{
    "error":"name not registred"
}

جستجو کردن یک آدرس

این سرویس یک جستجوی معکوس است. شما برای یک آدرس سوال می کنید و یک نام کاربری به شما باز می گردد اگر یکی از آنها در سرور نام ثبت شده باشد.

درخواست

یک درخواست برای ID jami:29347542eb07159f316577e1ae16243d152f6b7b یک درخواست GET است که /addr/29347542eb07159f316577e1ae16243d152f6b7b به عنوان URI.

پاسخ (موفقیت)

اگر آدرس با یک نام کاربری مطابقت داشته باشد، پاسخ با کد وضعیت 200 OK باید به مشتری با یک فیلدی Content-type به عنوان application/json ارسال شود.

این جسم یک سند JSON با یک صف است: name. ارزش این زمینه نام ثبت شده در این آدرس است

در مثال ما، پاسخ JSON این است:

{
    "name":"foobar"
}

پاسخ (نابودی)

اگر آدرس پیدا نشود، پاسخ با کد وضعیت 404 Not Found باید به مشتری با یک فیلدی Content-type به عنوان application/json ارسال شود.

این جسم یک سند JSON با یک صف است: error. این ویژگی با یک پیام خطا پر شده است که خطا را توضیح می دهد (و ممکن است در آینده در مشتری نمایش داده شود).

در مورد اجرای مرجع، سند بازگردانده شده عبارت است از:

{
    "error":"address not registred"
}

ثبت نام

این بخش از پروتکل برای ثبت یک جفت نام/ آدرس جدید استفاده می شود. این در ثبت عمومی اصلی استفاده می شود اما ممکن است در یک پیاده سازی سفارشی اختیاری باشد.

درخواست

یک درخواست برای ثبت نام نام foobar یک درخواست POST است که /name/foobar به عنوان URI. ویژگی عنوان Content-type باید به application/json تنظیم شود.

بدن درخواست یک سند JSON با 2 صف است: addr و owner. addr شامل شناسه Jami با پیشاپیش 0x و owner نام ثبت شده است.

یک مثال برای foobar می تواند:

{
    "addr":"0x29347542eb07159f316577e1ae16243d152f6b7b",
    "owner":"foobar"
}

پاسخ (موفقیت)

اگر زوج نام/ آدرس با موفقیت ثبت شود، پاسخ با کد وضعیت 200 OK باید به مشتری با یک فیلدی Content-type به عنوان application/json ارسال شود.

این جسم حاوی یک سند JSON با یک ویژگی boolean success تنظیم شده به true است.

به عنوان مثال:

{
    "success":true
}

در این صورت تلاش های بعدی برای دریافت نام یا آدرس باید موفق شود.

پاسخ (طلب بد)

اگر ثبت نام به دلیل یک خطا در درخواست (فرمت، ویژگی گم شده و غیره) انجام نشود، پاسخ با کد وضعیت 400 Bad Request باید به مشتری با یک فیلدی Content-type به عنوان application/json ارسال شود.

بدن یک سند JSON با 2 ویژگی است: success که یک boolean و error است که یک رشته است. success به false و error تنظیم شده است و با یک پیام خطا پر شده است که توضیح خطا (و ممکن است در آینده در مشتری نمایش داده شود).

برای فرمت نام کاربری ناشناس، بدن می تواند:

{
    "success": false,
    "error": "invalid name"
}

پاسخ (حظر شده)

اگر ثبت نام به دلیل نام قبلاً گرفته شده است، نمی توان انجام داد، پاسخ با کد وضعیت 403 Forbidden باید به مشتری با یک فیلدی Content-type که به عنوان application/json تنظیم شده است ارسال شود.

این جسم یک سند JSON با 3 ویژگی است: success که مجموعه boolean به false، name و addr است که هر دو رشته از درخواست اصلی تکرار شده اند.

ثبت foobar، با ثبت آن، منجر به پاسخ زیر خواهد شد:

{
    "success": false,
    "name":"foobar",
    "addr":"0x29347542eb07159fdeadbeefae16243d152f6b7b"
}