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

Aturan tentang format nama

Nama pengguna diperiksa oleh regex untuk memastikan beberapa aturan tentang formatnya:

  • Panjang harus antara 3 dan 32 karakter

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

Mencari nama

Ini adalah layanan utama yang disediakan oleh nama server. Ini memungkinkan mendapatkan ID Jami yang sesuai dengan nama pengguna.

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.

Dalam contoh kita, jawaban JSON akan:

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

Badan adalah dokumen JSON dengan 1 string atribut: error. Atribut ini diisi dengan pesan kesalahan yang menjelaskan kesalahan (dan bisa ditampilkan di klien di masa depan).

Pada implementasi referensi, dokumen yang dikembalikan adalah:

{
    "error":"name not registred"
}

Mencari alamat

Layanan ini adalah pencarian terbalik. Anda meminta alamat dan nama pengguna dikembalikan jika salah satu terdaftar di nama server.

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.

Badan adalah dokumen JSON dengan 1 atribut string: name. Nilai bidang ini adalah nama yang terdaftar di alamat ini

Dalam contoh kita, jawaban JSON akan:

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

Badan adalah dokumen JSON dengan 1 string atribut: error. Atribut ini diisi dengan pesan kesalahan yang menjelaskan kesalahan (dan bisa ditampilkan di klien di masa depan).

Pada implementasi referensi, dokumen yang dikembalikan adalah:

{
    "error":"address not registred"
}

Pendaftaran nama

Bagian ini dari protokol digunakan untuk mendaftarkan pasangan nama/alamat baru.

Request register

Permintaan untuk mendaftarkan nama foobar adalah permintaan POST dengan /name/foobar sebagai URI. Atribut header Content-type harus ditetapkan ke application/json.

Badan permintaan adalah dokumen JSON dengan 2 atribut string: addr dan owner. addr berisi ID Jami yang ditandai dengan 0x dan owner adalah nama yang harus terdaftar.

Contoh untuk foobar bisa:

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

Badan berisi dokumen JSON dengan 1 atribut boolean success ditetapkan untuk true.

Sebagai contoh:

{
    "success":true
}

Upaya lain untuk mencari nama atau alamat kemudian harus berhasil.

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.

Badan adalah dokumen JSON dengan 2 atribut: success yang merupakan boolean dan error yang merupakan string. success ditetapkan menjadi false dan error diisi dengan pesan kesalahan yang menjelaskan kesalahan (dan bisa ditampilkan di klien di masa depan).

Untuk format yang tidak valid dari nama pengguna, tubuh bisa:

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

Badan adalah dokumen JSON dengan 3 atribut: success yang merupakan himpunan boolean ke false, name dan addr yang keduanya adalah string yang direplikasi dari permintaan asli.

Pendaftaran foobar, karena sudah terdaftar, akan menyebabkan tanggapan sebagai berikut:

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