Nome Protocolo do servidor

O protocolo usado pelo Jami para consultar e registrar um nome é baseado em uma API HTTP REST que responde a solicitações com documentos JSON e códigos de status HTTP regulares.

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

Se você executar seu próprio servidor de nomes, procurar um nome de usuário na forma de username@example.com vai procurar o nome username com o servidor de nomes em example.com. (Não há necessidade de adicionar @ns.jami.net para usar o servidor de nomes padrão.)

Regras relativas à formatagem de nomes

Os nomes de usuários são verificados por um regex 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 -.

A fazer perguntas sobre um nome

Este é o principal serviço fornecido por um servidor de nomes.

Pedido

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

Resposta (sucesso)

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

O corpo é um documento JSON com 2 atributos de cadeia: 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 encontrada)

Se o nome não for encontrado, uma resposta com código de status 404 Not Found deve ser enviada ao cliente com um campo Content-type definido como application/json.

O corpo é um documento JSON com 1 atributo de cadeia: error. Este atributo é preenchido com uma mensagem de erro que explica o erro (e pode ser exibido no cliente no futuro).

No que diz respeito à execução de referência, o documento devolvido é:

{
    "error":"name not registred"
}

Pesquisas de endereço

Este serviço é uma busca inversa. Você consulta um endereço e um nome de usuário é devolvido se um está registrado no servidor de nomes.

Pedido

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

Resposta (sucesso)

Se o endereço corresponde a um nome de usuário, uma resposta com código de status 200 OK deve ser enviada ao cliente com um campo Content-type definido como application/json.

O corpo é um documento JSON com 1 atributo de linha: name. O valor deste campo é o nome registrado neste endereço

No nosso exemplo, a resposta JSON seria:

{
    "name":"foobar"
}

Resposta (Não encontrada)

Se o endereço não for encontrado, uma resposta com código de status 404 Not Found deve ser enviada ao cliente com um campo Content-type definido como application/json.

O corpo é um documento JSON com 1 atributo de cadeia: error. Este atributo é preenchido com uma mensagem de erro que explica o erro (e pode ser exibido no cliente no futuro).

No que diz respeito à execução de referência, o documento devolvido é:

{
    "error":"address not registred"
}

Registro de um nome

Esta parte do protocolo é usada para registrar um novo par de nome/adreça.

Pedido

Uma solicitação para registrar o nome foobar é uma solicitação 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 ID Jami prefixado com 0x e owner é o nome a ser registrado.

Um exemplo para foobar pode ser:

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

Resposta (sucesso)

Se o par nome/adreça for registrado com sucesso, deve ser enviada ao cliente uma resposta com código de status 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
}

Em seguida, as tentativas adicionais de consultar o nome ou o endereço deverão ser bem-sucedidas.

Resposta (perguntas negativas)

Se o registro não puder ser obtido devido a um erro na solicitação (formatação, atributo ausente etc.), uma resposta com o código de status 400 Bad Request deverá ser enviada ao cliente 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 cadeia. 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 formalização inválida do nome de usuário, o corpo pode ser:

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

Resposta (proibida)

Se o registro não puder ser feito porque o nome já foi usado, uma resposta com o código de status 403 Forbidden deverá ser enviada ao cliente com um campo Content-type definido como application/json.

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

O registro do foobar, com ele já registrado, levaria à seguinte resposta:

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