Name Serverprotokoll
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).
Regeln für die Namensformatierung
Benutzernamen werden von einem Regex überprüft, um einige Regeln über ihr Format zu gewährleisten:
Die Länge muss zwischen 3 und 32 Zeichen betragen
Those characters must be alphanumerical with dashes
-
being also accepted.
Ich frage nach einem Namen
Dies ist der Hauptdienst eines Nameservers, der es ermöglicht, die Jami-ID zu erhalten, die einem Benutzernamen entspricht.
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
.
In unserem Beispiel wäre die JSON-Antwort:
{
"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
.
Das Körper ist ein JSON-Dokument mit 1 Zeichenfolge-Attribut: error
. Dieses Attribut wird mit einer Fehlermeldung ausgefüllt, die den Fehler erklärt (und in Zukunft im Client angezeigt werden könnte).
Die zurückgegebene Unterlagen sind für die Referenzverwirklichung:
{
"error":"name not registred"
}
Anfrage nach Adresse
Dieser Service ist ein Reverse-Look-Up. Sie suchen nach einer Adresse und ein Benutzername wird zurückgegeben, wenn ein Benutzername auf dem Nameserver registriert ist.
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
.
Das Objekt ist ein JSON-Dokument mit einem Zeichenfolgeattribut: name
. Der Wert dieses Feldes ist der Name, der an diese Adresse registriert ist
In unserem Beispiel wäre die JSON-Antwort:
{
"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
.
Das Körper ist ein JSON-Dokument mit 1 Zeichenfolge-Attribut: error
. Dieses Attribut wird mit einer Fehlermeldung ausgefüllt, die den Fehler erklärt (und in Zukunft im Client angezeigt werden könnte).
Die zurückgegebene Unterlagen sind für die Referenzverwirklichung:
{
"error":"address not registred"
}
Registrierung eines Namens
Dieser Teil des Protokolls wird verwendet, um ein neues Name/Adress-Paar zu registrieren.
Request register
Eine Anfrage zur Registrierung des Namens foobar
ist eine POST
Anfrage mit /name/
foobar
als URI. Das Headerattribut Content-type
muss auf application/json
eingestellt werden.
Der Körper der Anfrage ist ein JSON-Dokument mit 2 Zeichenfolgeattributen: addr
und owner
. addr
enthält die Jami ID mit dem Präfix 0x
und owner
ist der Name, der registriert werden soll.
Ein Beispiel für foobar
könnte sein:
{
"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
.
Die Stelle enthält ein JSON-Dokument mit 1 boolean Attribut success
auf true
gesetzt.
Zum Beispiel:
{
"success":true
}
Weitere Versuche, den Namen oder die Adresse zu befragen, sollten dann erfolgreich sein.
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
.
Der Körper ist ein JSON-Dokument mit 2 Attributen: success
, das ist ein Boolean und error
, das ist eine Zeichenfolge. success
wird auf false
und error
eingestellt und mit einer Fehlermeldung gefüllt, die den Fehler erklärt (und könnte in der Zukunft im Client angezeigt werden).
Bei einer ungültigen Formatierung des Benutzernamens könnte der Körper sein:
{
"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
.
Das Körper ist ein JSON-Dokument mit 3 Attributen: success
, das eine booleanische Satz zu false
, name
und addr
ist, die beide Strings aus der ursprünglichen Anfrage repliziert sind.
Die Registrierung von foobar
, wenn sie bereits registriert ist, würde zu folgender Antwort führen:
{
"success": false,
"name":"foobar",
"addr":"0x29347542eb07159fdeadbeefae16243d152f6b7b"
}
Einige Verbindungen
gitlab:jami-nameservice: Referenz NodeJS Implementierung verwendet von
ns.jami.net
und die Abfrage eines Ethereum-Nodes.