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 jakoaplikacja/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"
}