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