Nom du protocole serveur

Le protocole utilisé par Jami pour demander et enregistrer un nom est basé sur une API HTTP [REST] (https://en.wikipedia.org/wiki/Representational_state_transfer) répondant aux demandes avec des documents JSON et des codes d’état HTTP réguliers.

Le serveur de noms public est hébergé à ns.jami.net et utilise une blockchain comme backend. Une autre mise en œuvre pourrait utiliser tout autre service de base de données ou de répertoire rendant le protocole de serveur de noms réutilisable.

Si vous exécutez votre propre serveur de noms, en recherchant un nom d’utilisateur sous la forme de username@example.com, vous chercherez le nom username avec le serveur de noms à example.com. (Il n’est pas nécessaire d’ajouter @ns.jami.net pour utiliser le serveur de noms par défaut.)

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.

Demande de réception

Une demande de nom foobar est une demande GET avec /nom/foobar comme URI.

Réponse (succès)

Si le nom est trouvé, une réponse avec le code de statut 200 OK doit être envoyée au client avec un champ Content-type définie comme application/json.

Le corps est un document JSON avec 2 attributs de chaîne: name et addr. name est égal à celui demandé et addr est une représentation hexadecimale de l’ID Jami préfiché avec 0x.

Dans notre exemple, la réponse JSON serait:

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

Réponse (non trouvée)

Si le nom n’est pas trouvé, une réponse avec le code de statut 404 Not Found doit être envoyée au client avec un champ Content-type définie comme 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.

Demande de réception

Une demande d’identification jami:29347542eb07159f316577e1ae16243d152f6b7b est une demande GET avec /addr/29347542eb07159f316577e1ae16243d152f6b7b` comme l’URI.

Réponse (succès)

Si l’adresse correspond à un nom d’utilisateur, une réponse avec le code de statut 200 OK doit être envoyée au client avec un champ Content-type définie comme 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"
}

Réponse (non trouvée)

Si l’adresse n’est pas trouvée, une réponse avec le code de statut 404 Not Found doit être envoyée au client avec un champ Content-type définie comme 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.

Demande de réception

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

Réponse (succès)

Si la paire nom/adresse est enregistrée avec succès, une réponse avec le code de statut 200 OK doit être envoyée au client avec un champ Content-type définie comme 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.

Réponse (mauvaise demande)

Si l’enregistrement ne peut être réalisé en raison d’une erreur dans la demande (formatation, défaut d’attribut, etc.), une réponse avec le code de statut 400 Bad Request doit être envoyée au client avec un champ Content-type défini comme 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"
}

Réponse (interdite)

Si l’enregistrement ne peut pas être réalisé parce que le nom est déjà pris, une réponse avec le code de statut 403 Forbidden doit être envoyée au client avec un champ Content-type définie comme 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"
}