Nome Protocolo do servidor

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

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

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 1 atributo de linha: name. O valor deste campo é o nome registrado neste 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 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.

Request register

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

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
}

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

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.

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

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