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

The protocol used by Jami to query and register a name is based on an HTTP REST API answering requests with JSON documents and regular HTTP status codes.

The public name server is hosted at ns.jami.net. Another implementation could use any other database or directory service making the name server protocol reusable.

If you run your own name server, looking up a username in the form of username@example.com will look up the name username with the name server at example.com (there is no need to add @ns.jami.net to use the default name server).

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

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

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

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

سوال کردن اسم

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

Request name

A request for the name foobar is a GET request with /name/foobar* as the URI.

Response name (Success)

If the name is found, a response with status code 200 OK must be sent to the client with a Content-type field set as application/json.

The body is a JSON documents with 2 string attributes : name and addr. name is equal to the one requested and addr is a hexadecimal representation of the Jami ID prefixed with 0x.

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

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

Response name (Not found)

If the name is not found, a response with status code 404 Not Found must be sent to the client with a Content-type field set as application/json.

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

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

{
    "error":"name not registred"
}

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

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

Request address

A request for the ID jami:29347542eb07159f316577e1ae16243d152f6b7b is a GET request with /addr/29347542eb07159f316577e1ae16243d152f6b7b as the URI.

Response address (Success)

If the address corresponds to a username, a response with status code 200 OK must be sent to the client with a Content-type field set as application/json.

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

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

{
    "name":"foobar"
}

Response address (Not found)

If the address is not found, a response with status code 404 Not Found must be sent to the client with a Content-type field set as application/json.

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

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

{
    "error":"address not registred"
}

ثبت نام

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

Request register

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

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

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

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

Response register (Success)

If the name/address pair is successfully registered, a response with status code 200 OK must be sent to the client with a Content-type field set as application/json.

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

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

{
    "success":true
}

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

Response register (Bad request)

If the registration is unable to be achieved because of an error in the request (formatting, missing attribute, etc.), a response with status code 400 Bad Request must be sent to the client with a Content-type field set as application/json.

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

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

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

Response register (Forbidden)

If the registration cannot be achieved because the name is already taken, a response with status code 403 Forbidden must be sent to the client with a Content-type field set as application/json.

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

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

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