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.

Nama server publik dihoskan di ns.jami.net dan menggunakan blockchain sebagai backend. Implementasi lain dapat menggunakan database atau layanan direktori lainnya sehingga protokol nama server dapat digunakan kembali.

Jika Anda menjalankan nama server Anda sendiri, mencari nama pengguna dalam bentuk username@example.com akan mencari nama username dengan nama server di example.com. (Tidak perlu menambahkan @ns.jami.net untuk menggunakan nama server standar.)

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.

Permintaan

Permintaan untuk nama foobar adalah permintaan GET dengan /name/foobar sebagai URI.

Tanggapan (Sukses)

Jika nama ditemukan, jawaban dengan kode status 200 OK harus dikirim ke klien dengan bidang Content-type ditetapkan sebagai application/json.

Badan adalah dokumen JSON dengan 2 atribut string: name dan addr. name sama dengan yang diminta dan addr adalah representasi heksadecimal dari ID Jami yang ditandai dengan 0x.

Dalam contoh kita, jawaban JSON akan:

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

Tanggapan (Tidak ditemukan)

Jika nama tidak ditemukan, sebuah jawaban dengan kode status 404 Not Found harus dikirim ke klien dengan bidang Content-type ditetapkan sebagai 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.

Permintaan

Permintaan untuk ID jami:29347542eb07159f316577e1ae16243d152f6b7b adalah permintaan GET dengan /addr/29347542eb07159f316577e1ae16243d152f6b7b sebagai URI.

Tanggapan (Sukses)

Jika alamat sesuai dengan nama pengguna, jawaban dengan kode status 200 OK harus dikirim ke klien dengan bidang Content-type ditetapkan sebagai 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"
}

Tanggapan (Tidak ditemukan)

Jika alamat tidak ditemukan, jawaban dengan kode status 404 Not Found harus dikirim ke klien dengan bidang Content-type ditetapkan sebagai 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.

Permintaan

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

Tanggapan (Sukses)

Jika pasangan nama/alamat berhasil terdaftar, jawaban dengan kode status 200 OK harus dikirim ke klien dengan bidang Content-type ditetapkan sebagai 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.

Tanggapan (permintaan buruk)

Jika pendaftaran tidak dapat dicapai karena kesalahan dalam permintaan (format, atribut yang hilang, dll.), tanggapan dengan kode status 400 Bad Request harus dikirim ke klien dengan bidang Content-type ditetapkan sebagai 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"
}

Tanggapan (dilarang)

Jika pendaftaran tidak dapat dicapai karena nama sudah diambil, jawaban dengan kode status 403 Forbidden harus dikirim ke klien dengan bidang Content-type ditetapkan sebagai 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"
}