Tên Protocol Server

Các giao thức được sử dụng bởi Jami để truy vấn và đăng ký một tên dựa trên HTTP [REST] (https://en.wikipedia.org/wiki/Representational_state_transfer) API trả lời các yêu cầu với tài liệu JSON và mã trạng thái HTTP thường xuyên.

Các máy chủ tên công cộng được lưu trữ tại ns.jami.net và sử dụng một blockchain như là hậu trường của nó.

Nếu bạn chạy máy chủ tên riêng của mình, tìm kiếm một tên người dùng dưới dạng username@example.com sẽ tìm kiếm tên người dùng với máy chủ tên ởexample.com. (Không cần thêm @ns.jami.net` để sử dụng máy chủ tên mặc định.)

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.

Yêu cầu

Một yêu cầu cho tên foobar là một yêu cầu GET với /name/foobar như URI.

Phản ứng (Sự thành công)

Nếu tên được tìm thấy, một câu trả lời với mã trạng thái 200 OK phải được gửi cho khách hàng với một trường Content-type được đặt là application/json.

Cơ thể là một tài liệu JSON với 2 thuộc tính chuỗi: name và addr. name bằng với yêu cầu và addr là một đại diện sáu thập kỷ của ID Jami được gắn với 0x.

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

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

Phản ứng (Không tìm thấy)

Nếu tên không được tìm thấy, một câu trả lời với mã trạng thái 404 Not Found phải được gửi đến khách hàng với một trường Content-type được đặt là 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.

Yêu cầu

Một yêu cầu về ID jami:29347542eb07159f316577e1ae16243d152f6b7b là một yêu cầu GET với /addr/29347542eb07159f316577e1ae16243d152f6b7b` như URI.

Phản ứng (Sự thành công)

Nếu địa chỉ tương ứng với tên người dùng, một câu trả lời với mã trạng thái 200 OK phải được gửi đến khách hàng với một trường Content-type được đặt là 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"
}

Phản ứng (Không tìm thấy)

Nếu không tìm thấy địa chỉ, một câu trả lời với mã trạng thái 404 Not Found phải được gửi đến khách hàng với một trường Content-type được đặt là 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.

Yêu cầu

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

Phản ứng (Sự thành công)

Nếu cặp tên/địa chỉ được đăng ký thành công, một câu trả lời với mã trạng thái 200 OK phải được gửi cho khách hàng với một trường Content-type được đặt là 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.

Phản ứng (phát đơn không tốt)

Nếu đăng ký không thể đạt được do lỗi trong yêu cầu (phát định, thuộc tính thiếu, v.v.), một câu trả lời với mã trạng thái 400 Bad Request phải được gửi đến khách hàng với một trường Content-type được đặt là 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"
}

Phản ứng (được cấm)

Nếu đăng ký không thể đạt được vì tên đã được lấy, một câu trả lời với mã trạng thái 403 Banned phải được gửi đến khách hàng với một trường Content-type được đặt là 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"
}