نام پروتکل سرور
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"
}
چندتا لینک
gitlab:jami-nameservice: اجرای NodeJS مرجع مورد استفاده توسط
ns.jami.net
و پرسیدن یک گره ایتیروم.