Nazwa Protokołu serwera
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).
Zasady dotyczące formatowania nazw
Nazwa użytkownika jest sprawdzana przez regex, aby zapewnić pewne zasady dotyczące ich formatu:
Długość musi wynosić od 3 do 32 znaków
Znaki te muszą być alfanumeryczne, a myślniki
-
są również akceptowane.
Zapytaj o nazwisko
Jest to główna usługa świadczona przez serwer nazw. Umożliwia uzyskanie identyfikatu Jami odpowiadającego nazwie użytkownika.
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
.
W naszym przykładzie odpowiedź JSON będzie:
{
"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
.
Ciała jest dokumentem JSON z atrybutem 1 wiersza: error
. Atrybut ten jest wypełniony wiadomością o błędzie wyjaśniającą błąd (i może być wyświetlana w klientze w przyszłości).
W odniesieniu do wdrożenia odniesienia zwrócony dokument brzmi:
{
"error":"name not registred"
}
Wykrywanie adresu
Usługa jest odwrotnym wyszukiwaniem. Zwraca się adres, a nazwa użytkownika jest zarejestrowana na serwerze nazw.
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
.
Certyfikat jest dokumentem JSON o atrybutie 1 wiersza: name
. Wartość tego pola jest nazwą zarejestrowaną na tym adresie
W naszym przykładzie odpowiedź JSON będzie:
{
"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
.
Ciała jest dokumentem JSON z atrybutem 1 wiersza: error
. Atrybut ten jest wypełniony wiadomością o błędzie wyjaśniającą błąd (i może być wyświetlana w klientze w przyszłości).
W odniesieniu do wdrożenia odniesienia zwrócony dokument brzmi:
{
"error":"address not registred"
}
Rejestracja nazwy
Ta część protokołu jest używana do rejestrowania nowej pary nazwy/adresów.
Request register
Wniosek o rejestrację nazwy foobar
jest wnioskiem POST
z /name/
foobar
jako URI. Atrybut nagłówka Content-type
musi być ustawiony na application/json
.
Wniosek zawiera dokument JSON o dwóch atrybutach: addr
i owner
. addr
zawiera identyfikator Jami z prefiksem 0x
i owner
jest nazwą do rejestracji.
Przykładem foobar
może być:
{
"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
.
Część zawiera dokument JSON z 1 atrybutem boolean success
ustawiony na true
.
Na przykład:
{
"success":true
}
Następne próby wyszukiwania nazwy lub adresu powinny być skuteczne.
Response register (Bad request)
If the registration cannot 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
.
Ciała jest dokumentem JSON o 2 atrybutach: success
, który jest boolean i error
, który jest ciągą. success
jest ustawiony na false
i error
jest wypełniony wiadomością błędu wyjaśniającą błąd (i może być wyświetlana w kliencie w przyszłości).
W przypadku nieprawidłowego formatowania nazwy użytkownika, ciało może być:
{
"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
.
Ciała jest dokumentem JSON o 3 atrybutach: success
, który jest zestawem boolean do false
, name
i addr
, które są obie wiersze replikowane z pierwotnego żądania.
Rejestracja foobar
, gdyż jest już zarejestrowana, doprowadziłaby do następującej odpowiedzi:
{
"success": false,
"name":"foobar",
"addr":"0x29347542eb07159fdeadbeefae16243d152f6b7b"
}
Niektóre linki
gitlab:jami-nameservice: odniesienie do implementacji NodeJS używanego przez
ns.jami.net
i zadawania zapytań węzła Ethereum.