Namn 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).

Regler för namnsformatering

Användarnamn kontrolleras av en regex för att säkerställa vissa regler om deras format:

  • Längden ska vara mellan 3 och 32 tecken

  • Those characters must be alphanumerical with dashes - being also accepted.

Fråga efter ett namn

Detta är den viktigaste tjänsten som tillhandahålls av en namnserver.

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.

I vårt exempel skulle svaret på JSON vara:

{
    "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.

Den är ett JSON-dokument med 1 strängattribut: error. Attributet fylles med ett felmeddelande som förklarar fel (och kan visas i klienten i framtiden).

När det gäller referensförslaget är det återlämnade dokumentet:

{
    "error":"name not registred"
}

Fråga om adress

Du frågar efter en adress och ett användarnamn returneras om ett är registrerat på namnservern.

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.

Den här fältet är ett JSON-dokument med ett attribut med en rad: name.

I vårt exempel skulle svaret på JSON vara:

{
    "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.

Den är ett JSON-dokument med 1 strängattribut: error. Attributet fylles med ett felmeddelande som förklarar fel (och kan visas i klienten i framtiden).

När det gäller referensförslaget är det återlämnade dokumentet:

{
    "error":"address not registred"
}

Registrering av ett namn

Denna del av protokollet används för att registrera ett nytt namn/adresspar.

Request register

En begäran om registrering av namnet foobar är en POST begäran med /namn/foobar som URI.

Den totala delen av begäran är ett JSON-dokument med två attribut: addr och owner. addr innehåller Jami ID med förfixet 0x och owner är det namn som ska registreras.

Ett exempel på foobar kan vara:

{
    "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.

Den innehåller ett JSON-dokument med 1 booleanattribut success som är inställd på true.

Som exempel:

{
    "success":true
}

Ytterligare försök att fråga om namn eller adress bör då lyckas.

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.

Den är ett JSON-dokument med 2 attribut: success som är en boolean och error som är en sträng. success är inställd på false och error är fylld med ett felmeddelande som förklarar fel (och kan visas i klienten i framtiden).

För en ogiltig formatering av användarnamnet kan kroppen vara:

{
    "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.

Den är ett JSON-dokument med 3 attribut: success som är ett booleansätt till false, name och addr som båda är strängar replikerade från den ursprungliga begäran.

Registrering av foobar, eftersom den redan är registrerad, skulle leda till följande svar:

{
    "success": false,
    "name":"foobar",
    "addr":"0x29347542eb07159fdeadbeefae16243d152f6b7b"
}