Nome Protocollo server

Il protocollo utilizzato da Jami per la consultazione e la registrazione di un nome si basa su un HTTP [REST] (https://en.wikipedia.org/wiki/Representational_state_transfer) API che risponde alle richieste con documenti JSON e codici di stato HTTP regolari.

Il nome pubblico è ospitato su ns.jami.net e utilizza una blockchain come suo backend.

Se si gestisce il proprio nome server, la ricerca di un nome utente sotto forma di username@example.com cercherà il nome username con il nome server a example.com. (Non è necessario aggiungere @ns.jami.net per utilizzare il nome server predefinito.)

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.

Richiesta

Una richiesta per il nome foobar è una richiesta GET con /name/foobar come URI.

Risposta (successo)

Se il nome viene trovato, una risposta con codice di stato 200 OK deve essere inviata al cliente con un campo Content-type impostato come application/json.

L’organismo è un documento JSON con 2 attributti di stringhe: name e addr. name è uguale a quello richiesto e addr è una rappresentazione esadecima dell’ID Jami prefisso con 0x.

Nel nostro esempio, la risposta JSON sarebbe:

{
    "name":"foobar",
    "addr":"0x29347542eb07159f316577e1ae16243d152f6b7b"
}

Risposta (Non trovata)

Se il nome non viene trovato, una risposta con codice di stato 404 Not Found deve essere inviata al cliente con un campo Content-type impostato come 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.

Richiesta

Una richiesta di ID jami:29347542eb07159f316577e1ae16243d152f6b7b è una richiesta GET con /addr/29347542eb07159f316577e1ae16243d152f6b7b come URI.

Risposta (successo)

Se l’indirizzo corrisponde a un nome utente, una risposta con codice di stato 200 OK deve essere inviata al cliente con un campo Content-type impostato come 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"
}

Risposta (Non trovata)

Se l’indirizzo non viene trovato, una risposta con codice di stato 404 Not Found deve essere inviata al cliente con un campo Content-type impostato come 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.

Richiesta

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

Risposta (successo)

Se la coppia di nome/indirizzo è registrata con successo, una risposta con codice di stato 200 OK deve essere inviata al cliente con un campo Content-type impostato come 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.

Risposta (cattiva richiesta)

Se la registrazione non può essere effettuata a causa di un errore nella richiesta (formattamento, attributo mancante, ecc.), una risposta con codice di stato 400 Bad Request deve essere inviata al cliente con un campo Content-type impostato come applicazione/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"
}

Risposta (proibita)

Se la registrazione non può essere effettuata perché il nome è già preso, una risposta con codice di stato 403 Forbidden deve essere inviata al cliente con un campo Content-type impostato come 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"
}