Protocolo do servidor de nomes

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

Regras de formatação de nomes

Os nomes de utilizador são verificados por uma expressão regular para garantir algumas regras sobre o seu formato:

  • O comprimento deve ser entre 3 e 32 caracteres

  • Estes caracteres devem ser alfanuméricos, sendo também aceites os traços -.

Consulta de um nome

Este é o principal serviço fornecido por um servidor de nomes. Permite obter o Jami ID correspondente a um nome de utilizador.

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.

No nosso exemplo, a resposta JSON seria:

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

O corpo é um documento JSON com um atributo string: error. Este atributo é preenchido com uma mensagem de erro que explica o erro (e que poderá ser mostrada no cliente no futuro).

Na implementação de referência, o documento devolvido é:

{
    "error":"name not registred"
}

Consulta de um endereço

Este serviço é uma pesquisa inversa. O utilizador consulta um endereço e é devolvido um nome de utilizador, se este estiver registado no servidor de nomes.

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.

O corpo é um documento JSON com um atributo de cadeia de caracteres: name. O valor deste campo é o nome registado para este endereço

No nosso exemplo, a resposta JSON seria:

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

O corpo é um documento JSON com um atributo string: error. Este atributo é preenchido com uma mensagem de erro que explica o erro (e que poderá ser mostrada no cliente no futuro).

Na implementação de referência, o documento devolvido é:

{
    "error":"address not registred"
}

Registar um nome

Esta parte do protocolo é utilizada para registar um novo par nome/endereço. É utilizada no registo público principal, mas pode ser opcional numa implementação personalizada.

Request register

Um pedido para registar o nome foobar é um pedido POST com /name/foobar como URI. O atributo de cabeçalho Content-type deve ser definido como application/json.

O corpo do pedido é um documento JSON com 2 atributos de cadeia: addr e owner. addr contém o Jami ID prefixado com 0x e owner é o nome a ser registado.

Um exemplo para foobar poderia ser:

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

O corpo contém um documento JSON com 1 atributo booleano success definido como true.

Como exemplo:

{
    "success":true
}

Outras tentativas de consultar o nome ou o endereço devem ser bem sucedidas.

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.

O corpo é um documento JSON com 2 atributos: success que é um booleano e error que é uma string. success é definido como false e error é preenchido com uma mensagem de erro que explica o erro (e pode ser exibido no cliente no futuro).

Para uma formatação inválida do nome de utilizador, o corpo pode ser:

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

O corpo é um documento JSON com 3 atributos: success que é um booleano definido como false, name e addr que são ambas strings replicadas do pedido original.

O registo de foobar, estando este já registado, conduziria à seguinte resposta:

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