Nome Protocollo server

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

Regole relative alla formattazione dei nomi

I nomi utente vengono controllati da un regex per assicurarsi alcune regole sul loro formato:

  • La lunghezza deve essere compresa tra 3 e 32 caratteri

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

Chiedendo un nome

Questo è il servizio principale fornito da un nome server.

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.

Nel nostro esempio, la risposta JSON sarebbe:

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

Il corpo è un documento JSON con un attributo di una stringia: error. Questo attributo è riempito da un messaggio di errore che spiega l’errore (e potrebbe essere visualizzato nel client in futuro).

Per quanto riguarda l’attuazione di riferimento, il documento restituito è:

{
    "error":"name not registred"
}

Inquesta di indirizzo

Questo servizio è un’analisi inversa. Si richiede un indirizzo e un nome utente viene restituito se uno è registrato sul server di nomi.

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.

Il corpo è un documento JSON con un attributo di una stringia: name. Il valore di questo campo è il nome registrato a questo indirizzo

Nel nostro esempio, la risposta JSON sarebbe:

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

Il corpo è un documento JSON con un attributo di una stringia: error. Questo attributo è riempito da un messaggio di errore che spiega l’errore (e potrebbe essere visualizzato nel client in futuro).

Per quanto riguarda l’attuazione di riferimento, il documento restituito è:

{
    "error":"address not registred"
}

Registrazione di un nome

Questa parte del protocollo è utilizzata per registrare una nuova coppia di nome/indirizzo.

Request register

Una richiesta di registrazione del nome foobar è una richiesta POST con /name/foobar come URI. L’attributo di intestazione Content-type deve essere impostato su application/json.

Il corpo della richiesta è un documento JSON con 2 attributti di stringhe: addr e owner. addr contiene l’ID Jami prefisso con 0x e owner è il nome da registrare.

Un esempio di foobar potrebbe essere:

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

Il corpo contiene un documento JSON con 1 attributo booleano success impostato su true.

Per esempio:

{
    "success":true
}

I tentativi ulteriori di richiedere il nome o l’indirizzo dovrebbero quindi avere successo.

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.

Il corpo è un documento JSON con 2 attributi: success che è un boolean e error che è una stringa. success è impostato su false e error è riempito di un messaggio di errore che spiega l’errore (e potrebbe essere visualizzato nel client in futuro).

Per un formato non valido del nome utente, l’organismo potrebbe essere:

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

Il corpo è un documento JSON con 3 attributi: success che è un insieme booleano di false, name e addr che sono entrambe le stringhe replicate dalla richiesta originale.

La registrazione foobar, già registrata, porterebbe alla seguente risposta:

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