名称服务器协议

贾米使用查询和注册名称的协议基于HTTP [REST] (https://en.wikipedia.org/wiki/Representational_state_transfer) API,以JSON文档和定期HTTP状态代码来响应请求.

公共名服务器设在 ns.jami.net,并使用区块链作为其后端.另一项实现可以使用任何其他数据库或目录服务,使名服务器协议可重复使用.

如果您运行自己的名服务器,在使用者名@example.com的形式搜索一个用户名,将在名服务器中搜索 username在 example.com. (不需要添加 @ns.jami.net`来使用默认名服务器).

名称格式化规则

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

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

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

查询一个名字

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

要求

‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧

反应 (成功)

如果找到名称,应向客户端发送一个状态代码的答案 200 OK,以 内容类型字段设为 应用/json.

‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧

在我们的例子中,JSON的答案是:

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

答案 (未找到)

如果名称未找到,应以状态代码 404 Not Found的答案发送给客户端,以 内容类型字段设为 应用/json.

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

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

{
    "error":"name not registred"
}

查询一个地址

您查询一个地址,如果一个用户名在名称服务器上注册,则会返回用户名.

要求

‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧ ‧

反应 (成功)

如果地址与用户名相符,则必须以状态代码 200 OK的回复发送给客户端,以 内容类型字段设为 应用/json.

实体是一个具有1字符串属性的JSON文档: name.该字段的值是该地址注册的名称

在我们的例子中,JSON的答案是:

{
    "name":"foobar"
}

答案 (未找到)

如果没有找到地址,应向客户端发送一个状态代码的答案 404 Not Found,以一个 内容类型字段设为 application/json.

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

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

{
    "error":"address not registred"
}

登记名称

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

要求

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

〇addr和 owner. addr包含前注: 0x和 owner`是注册的名称.

foobar的一个例子可以是:

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

反应 (成功)

如果名字/地址对成功注册,则必须向客户端发送一个状态代码的答案 200 OK,以 内容类型字段设为 应用/json.

实体包含一个 JSON 文档,其中有1个 boolean success设为 true.

举个例子:

{
    "success":true
}

进一步查询名称或地址的尝试将会成功.

答案 (不良请求)

如果由于请求中出现错误 (格式化,缺失属性等),则必须发送一个状态代码的回复 (400 Bad Request) 给客户端,以一个 () 内容类型字段设置为 (application/json).

实体是一个具有2个属性的JSON文档: success,这是一个布鲁尔语和 error,这是一个字符串. success设置为 false,并且 error填满了一个解释错误的错误信息 (将来可能会显示在客户端中).

对于用户名的不有效格式化,该机体可能是:

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

答案 (禁止)

如果由于名称已经被取名,无法进行注册,则必须向客户端发送一个状态代码的答案 403 禁止,以 内容类型字段设为 应用程序/json.

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

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

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