名称服务器协议

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

名称格式化规则

用户名字由Regex检查,以确保其格式有规则:

  • 长度必须在3至32个字符之间

  • Those characters must be alphanumerical with dashes - being also accepted.

查询一个名字

这是一个名字服务器提供的主要服务,它可以获得一个用户名的Jami ID.

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.

实体是一个具有1字符串属性的JSON文档: 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.

实体是一个具有1字符串属性的JSON文档: 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.

实体是一个具有1字符串属性的JSON文档: error. 这个属性包含了一个解释错误的错误信息 (将来可能会在客户端中显示).

关于参考实施,返回的文件是:

{
    "error":"address not registred"
}

登记名称

该协议的这一部分用于注册新的名称/地址对.它用于主要公开注册表,但在定制实现中可能是可选的.

Request register

〇foobar名字注册请求是 POST请求,以 /name/*foobar*为URI.标题属性 内容类型必须设置为 application/json`.

〇addr和 owner. addr包含前注: 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个 boolean 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.

实体是一个具有2个属性的JSON文档: 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.

实体是一个具有3个属性的JSON文档: success,这是一个布尔语集合的 false, name和 addr,这两个字符串都是从原始请求中复制的.

记载 foobar,已经注册,将导致以下反应:

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