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 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.

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