Názov protokol servera
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).
Pravidlá o formátovaní názvu
Používateľské mená sú kontrolované regexom, aby sa zabezpečili niektoré pravidlá týkajúce sa ich formátu:
Dĺžka musí byť od 3 do 32 znakov
Those characters must be alphanumerical with dashes
-
being also accepted.
Vyžiadať meno
Toto je hlavná služba poskytovaná serverom názvov. Umožňuje získať identifikáciu Jami zodpovedajúcu používateľskému mena.
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
.
V našom príklade by bola odpoveď na JSON:
{
"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
.
Tento atribút je naplnený chybovým správom, ktorý vysvetľuje chybu (a môže byť zobrazený v klientovi v budúcnosti).
V prípade referenčného vykonávania sa vrátený dokument označí:
{
"error":"name not registred"
}
Vyhľadávanie adresy
Táto služba je reverzné vyhľadávanie. Vyžiadate adresu a používateľské meno sa vráti, ak je registrované na server názvu.
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
.
Tvorba je JSON dokument s 1 znakom reťazca: name
. Hodnota tohto poľa je názov registrovaný na túto adresu
V našom príklade by bola odpoveď na JSON:
{
"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
.
Tento atribút je naplnený chybovým správom, ktorý vysvetľuje chybu (a môže byť zobrazený v klientovi v budúcnosti).
V prípade referenčného vykonávania sa vrátený dokument označí:
{
"error":"address not registred"
}
Registrácia názvu
Táto časť protokolu sa používa na zaregistrovanie nového paru názvu/adresu.
Request register
Žiadosť o registráciu názvu foobar
je žiadosť POST
s /name/
foobar
ako URI. Atribút hlavičky Content-type
musí byť nastavený na application/json
.
V rámci žiadosti je dokument JSON s 2 atribútmi reťazca: addr
a owner
. addr
obsahuje identifikátor Jami s predpisom 0x
a owner
je názov, ktorý sa má zaregistrovať.
Príkladom foobar
by mohol byť:
{
"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
.
Telo obsahuje JSON dokument s 1 booleánskym atribútom success
nastavený na true
.
Ako príklad:
{
"success":true
}
Ďalšie pokusy o vyhľadanie názvu alebo adresy by potom mali byť úspešné.
Response register (Bad request)
If the registration is unable to 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
.
Telo je JSON dokument s 2 atribútmi: success
, ktorý je booleánsky a error
, ktorý je reťazca. success
je nastavený na false
a error
je naplnený chybovým správom, ktorý vysvetľuje chybu (a môže byť zobrazený v klientovi v budúcnosti).
Pri neplatnom formátovaní používateľského mena by telo mohlo byť:
{
"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
.
Telo je JSON dokument s 3 atribútmi: success
, ktorý je booleánsky súbor na false
, name
a addr
, ktoré sú oba reťazce replikované z pôvodnej žiadosti.
Registrácia foobar
, keďže už bola zaregistrovaná, by viedla k nasledovnému odpovedi:
{
"success": false,
"name":"foobar",
"addr":"0x29347542eb07159fdeadbeefae16243d152f6b7b"
}
Niektoré prepojenia
gitlab:jami-nameservice: referenčné implementácie NodeJS používané
ns.jami.net
a dotazy o Ethereum uzl.