Tên Protocol Server

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

Quy tắc định dạng tên

Tên người dùng được kiểm tra bởi một regex để đảm bảo một số quy tắc về định dạng của chúng:

  • Độ dài phải từ 3 đến 32 ký tự

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

Tìm kiếm tên

Đây là dịch vụ chính được cung cấp bởi một máy chủ tên. Nó cho phép nhận được ID Jami tương ứng với một tên người dùng.

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.

Trong ví dụ của chúng tôi, câu trả lời JSON sẽ là:

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

Cơ thể là một tài liệu JSON với 1 thuộc tính chuỗi: error. thuộc tính này được lấp đầy với một thông báo lỗi giải thích lỗi (và có thể được hiển thị trong client trong tương lai).

Về việc thực hiện tham chiếu, tài liệu trả lại là:

{
    "error":"name not registred"
}

Tìm kiếm địa chỉ

Dịch vụ này là tìm kiếm ngược. Bạn truy vấn một địa chỉ và một tên người dùng sẽ được trả lại nếu một tên đăng ký trên máy chủ tên.

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.

Cơ thể là một tài liệu JSON với 1 thuộc tính chuỗi: name. Giá trị của trường này là tên đăng ký vào địa chỉ này

Trong ví dụ của chúng tôi, câu trả lời JSON sẽ là:

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

Cơ thể là một tài liệu JSON với 1 thuộc tính chuỗi: error. thuộc tính này được lấp đầy với một thông báo lỗi giải thích lỗi (và có thể được hiển thị trong client trong tương lai).

Về việc thực hiện tham chiếu, tài liệu trả lại là:

{
    "error":"address not registred"
}

Đăng ký tên

Phần này của giao thức được sử dụng để đăng ký một cặp tên / địa chỉ mới. Nó được sử dụng trên đăng ký công cộng chính nhưng có thể là tùy chọn trong một thực hiện tùy chỉnh.

Request register

Một yêu cầu đăng ký tên foobar là một yêu cầu POST với /name/foobar như URI.

Cơ thể của yêu cầu là một tài liệu JSON với 2 thuộc tính chuỗi: addr và owner. addr chứa ID Jami được gắn với 0x và owner là tên để đăng ký.

Một ví dụ cho foobar có thể là:

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

Cơ thể chứa một tài liệu JSON với 1 thuộc tính boolean success được thiết lập thành true.

Ví dụ:

{
    "success":true
}

Sau đó, các nỗ lực tìm kiếm tên hoặc địa chỉ sẽ thành công.

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.

Cơ thể là một tài liệu JSON với 2 thuộc tính: success là một boolean và error là một chuỗi. success được đặt là false và error được lấp đầy với một thông báo lỗi giải thích lỗi (và có thể được hiển thị trong khách hàng trong tương lai).

Đối với định dạng không hợp lệ của tên người dùng, cơ thể có thể là:

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

Cơ thể là một tài liệu JSON với 3 thuộc tính: success là một tập hợp boolean cho false, name và addr, cả hai đều là chuỗi sao chép từ yêu cầu ban đầu.

Việc đăng ký foobar, khi nó đã được đăng ký, sẽ dẫn đến phản ứng sau:

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