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