Nombre Protocol del servidor

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

Regles sobre formatatge de noms

Els noms d’usuari són verificats per un regex per assegurar algunes normes sobre el seu format:

  • La longitud ha de ser entre 3 i 32 caràcters

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

Buscant un nom

Aquest és el servei principal proporcionat per un servidor de noms.

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.

En el nostre exemple, la resposta JSON seria:

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

El còdi és un document JSON amb un atribut de cadena: error. Aquest atribut està omplert amb un missatge d’error que explica l’error (i podria ser visualitzat en el client en el futur).

En relació amb la implementació de referència, el document retornat és:

{
    "error":"name not registred"
}

Requesting una adreça

Aquest servei és una recerca inversa. Se pregunta per una adreça i un nom d’usuari es torna si un està registrat en el servidor 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.

El cos és un document JSON amb un atribut de cadena: name. El valor d’aquest camp és el nom registrat a aquesta adreça

En el nostre exemple, la resposta JSON seria:

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

El còdi és un document JSON amb un atribut de cadena: error. Aquest atribut està omplert amb un missatge d’error que explica l’error (i podria ser visualitzat en el client en el futur).

En relació amb la implementació de referència, el document retornat és:

{
    "error":"address not registred"
}

Registreix un nom

Aquesta part del protocol s’utilitza per registrar un nou parell de nom/adreça.

Request register

Una sol·licitud per a registrar el nom foobar és una sol·licitud POST amb /name/foobar com a URI. L’atribut de cap de cap Content-type ha de ser establert en application/json.

El cos de la petició és un document JSON amb 2 atributs de cadena: addr i owner. addr conté l’ID Jami prefixat amb 0x i owner és el nom que s’ha de registrar.

Un exemple per foobar podria ser:

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

El cos conté un document JSON amb 1 atribut booleà success establert en true.

Com a exemple:

{
    "success":true
}

Els intents més anteriors de consultar el nom o l’adreça han de tenir èxit.

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.

El còdi és un document JSON amb 2 atributs: success que és un boolean i error que és una cadena. success està establert a false i error està omplit amb un missatge d’error que explica l’error (i podria ser visualitzat en el client en el futur).

Per a una formatització invalida del nom d’usuari, el cos podria ser:

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

L’organisme és un document JSON amb 3 atributs: success que és un conjunt booleà de false, name i addr que són dues cadenes replicades de la sol·licitud original.

La inscripció foobar, ja que ja està registrada, portaria a la següent resposta:

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