Nazwa Protokołu serwera
Protokół używany przez Jami do zapytania i rejestracji nazwy opiera się na HTTP [REST] (https://en.wikipedia.org/wiki/Representational_state_transfer) API odpowiadającym na żądania z dokumentami JSON i regularnymi kodami statusu HTTP.
Publiczny serwer nazw jest hostowany na ns.jami.net
i wykorzystuje blockchain jako jego backend.
Jeśli uruchomiasz własny serwer nazw, wyszukiwanie nazwy użytkownika w postaci username@example.com
będzie wyszukiwać nazwę username
z serwerem nazw na example.com
. (Nie ma potrzeby dodawania @ns.jami.net
do użycia domyślnego serwera nazw.)
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.
Wniosek
Wniosek o nazwę foobar
jest wnioskiem GET
z /nazwą/
foobar
jako URI.
Odpowiedź (powodzony)
Jeżeli nazwa zostanie znaleziona, odpowiedź z kodem statusu 200
OK
musi zostać przesłana do klienta z Typem treści
pole ustawione jako application/json
.
Część jest dokumentem JSON o 2 atrybutach wiersza: name
i addr
. name
jest równa do wymaganej i addr
jest sześćdziesięcioletnim przedstawieniem identyfikatu Jami z prefiksem 0x
.
W naszym przykładzie odpowiedź JSON będzie:
{
"name":"foobar",
"addr":"0x29347542eb07159f316577e1ae16243d152f6b7b"
}
Odpowiedź (Nie znaleziono)
Jeżeli nazwę nie znajdziemy, odpowiedź z kodem statusu 404
Not
Find
musi zostać przesłana do klienta z Content-type
pole ustawione jako 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.
Wniosek
Wniosek o identyfikację jami:29347542eb07159f316577e1ae16243d152f6b7b
jest wnioskiem GET
z /addr/
29347542eb07159f316577e1ae16243d152f6b7b` jako URI.
Odpowiedź (powodzony)
Jeżeli adres odpowiada nazwie użytkownika, odpowiedź z kodem statusu 200
OK
musi zostać przesłana do klienta z pole Content-type
ustawione jako 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"
}
Odpowiedź (Nie znaleziono)
Jeżeli adres nie zostanie znaleziony, odpowiedź z kodem statusu 404
Not
Find
musi zostać przesłana do klienta z Content-type
pole ustawione jako 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.
Wniosek
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"
}
Odpowiedź (powodzony)
Jeżeli para nazwy/adres jest zarejestrowana z powodzeniem, odpowiedź z kodem statusu 200
OK
musi zostać przesłana do klienta z pola Content-type
ustawionym jako 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.
Odpowiedź (złe żądanie)
Jeżeli rejestracja nie może zostać zrealizowana z powodu błędu w żądanie (formatyzacja, brakujące atrybut itp.), odpowiedź z kodem statusu 400
Bad
Request
musi zostać przesłana do klienta z Wyznaniem typu
pole ustawione jako
aplikacja/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"
}
Odpowiedź (zakazane)
Jeżeli rejestracja nie może zostać zrealizowana, ponieważ nazwa jest już przyjęta, odpowiedź z kodem statusu 403
Forbidden
musi zostać przesłana do klienta z Content-type
pole ustawione jako 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.