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

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.

Тело запроса представляет собой документ 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 cannot 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"
}