Nom du protocole serveur
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).
Règles relatives au formatage des noms
Les noms d’utilisateur sont vérifiés par un régex pour s’assurer que certaines règles concernant leur format:
La longueur doit être comprise entre 3 et 32 caractères
Those characters must be alphanumerical with dashes
-
being also accepted.
Je cherche un nom
C’est le service principal fourni par un serveur de noms. Il permet d’obtenir l’identifiant Jami correspondant à un nom d’utilisateur.
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
.
Dans notre exemple, la réponse JSON serait:
{
"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
.
Le corps est un document JSON avec un attribut de chaîne : error
. Cet attribut est rempli d’un message d’erreur qui explique l’erreur (et pourrait être affiché dans le client à l’avenir).
En ce qui concerne la mise en œuvre de référence, le document retourné est le suivant:
{
"error":"name not registred"
}
Recherche d’une adresse
Ce service est une recherche inverse. Vous demandez une adresse et un nom d’utilisateur est retourné si l’un est enregistré sur le serveur de noms.
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
.
Le corps est un document JSON avec un attribut de chaîne : name
. La valeur de ce champ est le nom enregistré à cette adresse
Dans notre exemple, la réponse JSON serait:
{
"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
.
Le corps est un document JSON avec un attribut de chaîne : error
. Cet attribut est rempli d’un message d’erreur qui explique l’erreur (et pourrait être affiché dans le client à l’avenir).
En ce qui concerne la mise en œuvre de référence, le document retourné est le suivant:
{
"error":"address not registred"
}
Enregistrement d’un nom
Cette partie du protocole est utilisée pour enregistrer une nouvelle paire de nom/adresse.
Request register
Une demande d’enregistrement du nom foobar
est une demande POST
avec /name/
foobar
comme URI. L’attribut d’en-tête Content-type
doit être réglé sur application/json
.
Le corps de la demande est un document JSON avec 2 attributs de chaîne: addr
et owner
. addr
contient l’ID Jami préfiché avec 0x
et owner
est le nom à enregistrer.
Un exemple de foobar
pourrait être:
{
"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
.
Le corps contient un document JSON avec 1 attribut booléen success
définie à true
.
À titre d’exemple:
{
"success":true
}
Les tentatives ultérieures de recherche du nom ou de l’adresse devraient alors réussir.
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
.
Le corps est un document JSON avec 2 attributs: success
qui est un booléen et error
qui est une chaîne. success
est réglé sur false
et error
est rempli d’un message d’erreur qui explique l’erreur (et pourrait être affiché dans le client à l’avenir).
Pour une mise en forme non valide du nom d’utilisateur, le corps peut être:
{
"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
.
Le corps est un document JSON avec 3 attributs: success
qui est un ensemble booléen de false
, name
et addr
qui sont toutes deux des chaînes reproduites à partir de la demande originale.
L’enregistrement de foobar
, étant déjà enregistré, conduirait à la réponse suivante:
{
"success": false,
"name":"foobar",
"addr":"0x29347542eb07159fdeadbeefae16243d152f6b7b"
}
Quelques liens
: référence NodeJS mise en œuvre utilisée par
ns.jami.net
et la requête d’un nœud Ethereum.