Name Serverprotokoll
Das von Jami verwendete Protokoll zur Abfrage und Registrierung eines Namens basiert auf einer HTTP [REST] (https://en.wikipedia.org/wiki/Representational_state_transfer) API, die Anfragen mit JSON-Dokumenten und regelmäßigen HTTP-Statuscodes beantwortet.
Der öffentliche Nameserver ist unter ns.jami.net
gehostet und verwendet eine Blockchain als Backend. Eine andere Implementierung könnte jede andere Datenbank oder Verzeichnisdienst verwenden, die das Nameserver-Protokoll wiederverwendbar macht.
Wenn Sie Ihren eigenen Nameserver betreiben, suchen Sie nach einem Benutzernamen in Form von username@example.com
, dann suchen Sie den Namen username
mit dem Nameserver unter example.com
. (Es ist nicht erforderlich, @ns.jami.net
hinzuzufügen, um den Standardnameserver zu verwenden.)
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.
Anfrage
Eine Anfrage nach dem Namen foobar
ist eine GET
Anfrage mit /name/
foobar
als URI.
Reaktion (Erfolg)
Wenn der Name gefunden wird, muss eine Antwort mit Statuscode 200
OK
an den Kunden mit einem Content-Type
Feld mit application/json
gesendet werden.
Das Organ ist ein JSON-Dokument mit 2 Zeichenfolgeattributen: name
und addr
. name
ist gleich dem angeforderten und addr
ist eine sechsezeimal dargestellte Darstellung der Jami ID mit 0x
.
In unserem Beispiel wäre die JSON-Antwort:
{
"name":"foobar",
"addr":"0x29347542eb07159f316577e1ae16243d152f6b7b"
}
Antwort (nicht gefunden)
Wenn der Name nicht gefunden wird, muss eine Antwort mit Statuscode 404
Not
Found
an den Kunden mit einem Content-Type
Feld als application/json
gesendet werden.
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.
Anfrage
Eine Anfrage nach der ID jami:29347542eb07159f316577e1ae16243d152f6b7b
ist eine GET
Anfrage mit /addr/
29347542eb07159f316577e1ae16243d152f6b7b
als URI.
Reaktion (Erfolg)
Wenn die Adresse einem Benutzernamen entspricht, muss der Kunde eine Antwort mit dem Statuscode 200
OK
mit einem Content-type
Feld als application/json
gesendet werden.
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"
}
Antwort (nicht gefunden)
Wenn die Adresse nicht gefunden wird, muss eine Antwort mit Statuscode 404
Not
Find
an den Kunden mit einem Content-type
Feld als application/json
gesendet werden.
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.
Anfrage
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"
}
Reaktion (Erfolg)
Wenn das Name/Adresse-Paar erfolgreich registriert ist, muss der Kunde eine Antwort mit dem Statuscode 200
OK
mit einem Content-Type
Feld als application/json
gesendet werden.
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.
Antwort (schlechte Anfrage)
Wenn die Registrierung aufgrund eines Fehlers in der Anfrage (Formatierung, fehlende Attribut usw.) nicht erreicht werden kann, muss der Kunde eine Antwort mit dem Statuscode 400
Bad
Request
mit einem Content-type
Feld als application/json
gesendet werden.
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"
}
Antwort (Verboten)
Wenn die Registrierung nicht möglich ist, weil der Name bereits verwendet wurde, muss der Kunde eine Antwort mit dem Statuscode 403
Forbidden
mit einem Content-type
Feld als application/json
gesendet werden.
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.