Нарича се протокол на сървъра

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

Правила за форматиране на имената

Потребителските имена се проверяват от регекс, за да се гарантира някои правила за формата им:

  • Дължина трябва да бъде между 3 и 32 символа

  • Those characters must be alphanumerical with dashes - being also accepted.

Искаме име

Това е основната услуга, която се предоставя от сървър на имена.

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 документ с 1 атрибут на редица: 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 документ с 1 атрибут на реже: 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 документ с 1 атрибут на редица: 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 документ с 1 булеански атрибут 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, който е булеански и 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, което е буленски набор от false, name и addr, които са и двете репликирани от първоначалното искане.

Регистрирането на foobar, тъй като вече е регистрирано, би довело до следното откликване:

{
    "success": false,
    "name":"foobar",
    "addr":"0x29347542eb07159fdeadbeefae16243d152f6b7b"
}