Название Протокол сервера

Протокол, используемый Джами для запроса и регистрации имени, основан на HTTP [REST] (https://en.wikipedia.org/wiki/Representational_state_transfer) API, отвечающем на запросы с документами JSON и регулярными кодами статуса HTTP.

Общественный сервер имен размещается на ns.jami.net и использует блокчейн в качестве своего бэкэнда.

Если вы управляете собственным именным сервером, поиск имени пользователя в форме username@example.com будет искать имя username с именным сервером на example.com. (Не нужно добавлять @ns.jami.net для использования дефолтного именного сервера.)

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

Пользовательские имена проверяются регекс, чтобы обеспечить некоторые правила о их формате:

  • Длина должна быть от 3 до 32 символов

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

Задаю вопрос о имени

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

Запрос

Запрос на имя foobar является запросом GET с /name/foobar как URI.

Ответ (успех)

Если имя найдено, ответ с кодом статуса 200 OK должен быть отправлен клиенту с Content-type полем, установленным как application/json.

Тело представляет собой JSON-документ с 2 строками: name и addr. name равен запрошенному, а addr представляет собой шестидесятное представление идентификатора Jami с предварительным знаком 0x.

В нашем примере ответ на JSON будет:

{
    "name":"foobar",
    "addr":"0x29347542eb07159f316577e1ae16243d152f6b7b"
}

Ответ (не найден)

Если имя не найдено, ответ с кодом статуса 404 Not Found должен быть отправлен клиенту с Content-type полем, установленным как application/json.

Тело представляет собой JSON-документ с 1 строкой атрибута : error. Этот атрибут заполнен сообщением об ошибке, объясняющим ошибку (и может быть отображен в клиенте в будущем).

По поводу реализации ссылки возвращенный документ:

{
    "error":"name not registred"
}

Запрос по адресу

Вы запрашиваете адрес, и имя пользователя возвращается, если оно зарегистрировано на сервере имен.

Запрос

Запрос на идентификационный номер jami:29347542eb07159f316577e1ae16243d152f6b7b является запросом GET с /addr/29347542eb07159f316577e1ae16243d152f6b7b` как URI.

Ответ (успех)

Если адрес соответствует имени пользователя, ответ с кодом статуса 200 OK должен быть отправлен клиенту с Content-type полем, установленным как application/json.

Тело представляет собой JSON-документ с 1 строкой атрибута : name. Значение этого поля - это имя, зарегистрированное на этом адресе

В нашем примере ответ на JSON будет:

{
    "name":"foobar"
}

Ответ (не найден)

Если адрес не найден, ответ с кодом статуса 404 Not Found должен быть отправлен клиенту с Content-type полем, установленным как application/json.

Тело представляет собой JSON-документ с 1 строкой атрибута : error. Этот атрибут заполнен сообщением об ошибке, объясняющим ошибку (и может быть отображен в клиенте в будущем).

По поводу реализации ссылки возвращенный документ:

{
    "error":"address not registred"
}

Регистрация имени

Эта часть протокола используется для регистрации новой пары имени/адреса.

Запрос

Запрос о регистрации имени foobar представляет собой запрос POST с /name/foobar как URI.

Тело запроса представляет собой документ JSON с 2 атрибутами строки: addr и owner. addr содержит идентификатор Jami с предварительным фиксом 0x и owner является имя, которое должно быть зарегистрировано.

Примером для foobar может быть:

{
    "addr":"0x29347542eb07159f316577e1ae16243d152f6b7b",
    "owner":"foobar"
}

Ответ (успех)

Если пара имени/адреса успешно зарегистрирована, ответ с кодом статуса 200 OK должен быть отправлен клиенту с Content-type полем, установленным как application/json.

В корпусе содержится JSON-документ с 1 булевым атрибутом success, установленный на true.

Например:

{
    "success":true
}

Дальнейшие попытки запроса имени или адреса должны быть успешными.

Ответ (неблагоприятный запрос)

Если регистрация не может быть осуществлена из-за ошибки в запросе (форматирование, отсутствие атрибута и т.д.), ответ с кодом статуса 400 Bad Request должен быть отправлен клиенту с Content-type полем, установленным как application/json.

Тело представляет собой JSON-документ с 2 атрибутами: success, который является булевым и error, который является строкой. success установлен на false и error заполнен сообщением об ошибке, объясняющим ошибку (и может быть отображен в клиенте в будущем).

Для недействительного форматирования имени пользователя, тело может быть:

{
    "success": false,
    "error": "invalid name"
}

Ответ (запрещен)

Если регистрация не может быть осуществлена, потому что имя уже принято, ответ с кодом статуса 403 Запрещен должен быть отправлен клиенту с Content-type полем, установленным как application/json.

Тело представляет собой JSON-документ с 3 атрибутами: success, который является булевым набором на false, name и addr, которые являются строками, воспроизведенными из исходного запроса.

Регистрация foobar, если она уже зарегистрирована, приведет к следующему ответу:

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