Protocolo do servidor de nomes

O protocolo utilizado pelo Jami para consultar e registar um nome baseia-se numa API HTTP REST que responde a pedidos com documentos JSON e códigos de estado HTTP normais.

O servidor de nomes público está hospedado em ns.jami.net e usa um blockchain como backend. Outra implementação poderia usar qualquer outra base de dados ou serviço de diretório, tornando o protocolo do servidor de nomes reutilizável.

Se tiver o seu próprio servidor de nomes, procurar um nome de utilizador na forma de username@example.com irá procurar o nome username com o servidor de nomes em example.com. (Não há necessidade de adicionar @ns.jami.net para utilizar o servidor de nomes padrão).

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.

Pedido

Um pedido para o nome foobar é um pedido GET com /name/foobar como o URI.

Resposta (sucesso)

Se o nome for encontrado, deve ser enviada ao cliente uma resposta com o código de estado 200 OK com o campo Content-type definido como application/json.

O corpo é um documento JSON com 2 atributos string : name e addr. name é igual ao solicitado e addr é uma representação hexadecimal do ID Jami prefixado com 0x.

No nosso exemplo, a resposta JSON seria:

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

Resposta (não encontrado)

Se o nome não for encontrado, deve ser enviada ao cliente uma resposta com o código de estado 404 Not Found com um campo Content-type definido como 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.

Pedido

Um pedido para o ID jami:29347542eb07159f316577e1ae16243d152f6b7b é um pedido GET com /addr/29347542eb07159f316577e1ae16243d152f6b7b como URI.

Resposta (sucesso)

Se o endereço corresponder a um nome de utilizador, deve ser enviada ao cliente uma resposta com o código de estado 200 OK com um campo Content-type definido como 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"
}

Resposta (não encontrado)

Se o endereço não for encontrado, deve ser enviada ao cliente uma resposta com o código de estado 404 Not Found com um campo Content-type definido como 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.

Pedido

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

Resposta (sucesso)

Se o par nome/endereço for registado com êxito, deve ser enviada ao cliente uma resposta com o código de estado 200 OK com um campo Content-type definido como 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.

Resposta (pedido incorreto)

Se o registo não puder ser efetuado devido a um erro no pedido (formatação, atributo em falta, etc.), deve ser enviada ao cliente uma resposta com o código de estado 400 Bad Request com um campo Content-type definido como 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"
}

Resposta (proibido)

Se não for possível efetuar o registo porque o nome já está atribuído, deve ser enviada ao cliente uma resposta com o código de estado 403 Forbidden com um campo Content-type definido como 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"
}