Nombre Protocolo del servidor
El protocolo utilizado por Jami para consultar y registrar un nombre se basa en una API HTTP [REST] (https://en.wikipedia.org/wiki/Representational_state_transfer) que responde a las solicitudes con documentos JSON y códigos de estado HTTP regulares.
El servidor de nombres público está alojado en ns.jami.net
y utiliza una cadena de bloques como su backend. Otra implementación podría utilizar cualquier otro servicio de base de datos o directorio que haga reutilizar el protocolo del servidor de nombres.
Si ejecuta su propio servidor de nombres, buscar un nombre de usuario en la forma de username@example.com
buscará el nombre username
con el servidor de nombres en example.com
. (No es necesario añadir @ns.jami.net
para usar el servidor de nombres predeterminado.)
Reglas sobre el formato de los nombres
Los nombres de usuario son verificados por un regex para asegurar algunas reglas sobre su formato:
La longitud debe ser de entre 3 y 32 caracteres
Estos caracteres deben ser alfanuméricos y también debe aceptarse el guión
-
.
Buscando un nombre
Este es el servicio principal proporcionado por un servidor de nombres.
Solicitud
Una solicitud de nombre foobar
es una solicitud GET
con /name/
foobar
como URI.
Respuesta (éxito)
Si se encuentra el nombre, se debe enviar al cliente una respuesta con código de estado 200
OK
con un campo Tip Content
definido como application/json
.
El cuerpo es un documento JSON con 2 atributos de cadena: name
y addr
. name
es igual al solicitado y addr
es una representación hexadecimal del ID Jami prefijado con 0x
.
En nuestro ejemplo, la respuesta JSON sería:
{
"name":"foobar",
"addr":"0x29347542eb07159f316577e1ae16243d152f6b7b"
}
Respuesta (No se encuentra)
Si el nombre no se encuentra, una respuesta con código de estado 404
Not
Found
debe enviarse al cliente con un campo Content-type
fijado como application/json
.
El cuerpo es un documento JSON con un atributo de cadena: error
. Este atributo está lleno de un mensaje de error que explica el error (y podría mostrarse en el cliente en el futuro).
En relación con la ejecución de referencia, el documento devuelto será:
{
"error":"name not registred"
}
Buscando una dirección
Este servicio es una búsqueda inversa. Usted consulta una dirección y un nombre de usuario se devuelve si uno está registrado en el servidor de nombres.
Solicitud
Una solicitud de ID jami:29347542eb07159f316577e1ae16243d152f6b7b
es una solicitud GET
con /addr/
29347542eb07159f316577e1ae16243d152f6b7b
como el URI.
Respuesta (éxito)
Si la dirección corresponde a un nombre de usuario, se debe enviar al cliente una respuesta con código de estado 200
OK
con un campo Content-type
definido como application/json
.
El cuerpo es un documento JSON con un atributo de cadena: name
. El valor de este campo es el nombre registrado en esta dirección
En nuestro ejemplo, la respuesta JSON sería:
{
"name":"foobar"
}
Respuesta (No se encuentra)
Si la dirección no se encuentra, una respuesta con código de estado 404
Not
Found
debe enviarse al cliente con un campo Content-type
fijado como application/json
.
El cuerpo es un documento JSON con un atributo de cadena: error
. Este atributo está lleno de un mensaje de error que explica el error (y podría mostrarse en el cliente en el futuro).
En relación con la ejecución de referencia, el documento devuelto será:
{
"error":"address not registred"
}
Registro de un nombre
Esta parte del protocolo se utiliza para registrar un nuevo par de nombres/direcciones.
Solicitud
Una solicitud de registro del nombre foobar
es una solicitud POST
con /name/
foobar
como URI. El atributo de encabezado Content-type
debe fijarse en application/json
.
El cuerpo de la solicitud es un documento JSON con 2 atributos de cadena: addr
y owner
. addr
contiene el ID Jami prefijado con 0x
y owner
es el nombre que debe registrarse.
Un ejemplo de foobar
podría ser:
{
"addr":"0x29347542eb07159f316577e1ae16243d152f6b7b",
"owner":"foobar"
}
Respuesta (éxito)
Si el par nombre/dirección se registra con éxito, se deberá enviar al cliente una respuesta con código de estado 200
OK
con un campo content-type
fijado como application/json
.
El cuerpo contiene un documento JSON con 1 atributo booleano success
fijado en true
.
Como ejemplo:
{
"success":true
}
Los intentos adicionales de consultar el nombre o la dirección deberían entonces tener éxito.
Respuesta (petición negativa)
Si el registro no puede lograrse debido a un error en la solicitud (formatización, falta de atributo, etc.), se debe enviar al cliente una respuesta con código de estado 400
Bad
Request
con un campo Content-type
establecido como application/json
.
El cuerpo es un documento JSON con 2 atributos: success
que es un boolean y error
que es una cadena. success
se establece en false
y error
se llena de un mensaje de error que explica el error (y podría mostrarse en el cliente en el futuro).
Para un formato inválido del nombre de usuario, el cuerpo podría ser:
{
"success": false,
"error": "invalid name"
}
Respuesta (prohibido)
Si el registro no puede lograrse porque el nombre ya está tomado, se debe enviar al cliente una respuesta con código de estado 403
Forbidden
con un campo Content-type
establecido como application/json
.
El cuerpo es un documento JSON con 3 atributos: success
que es un conjunto booleano de false
, name
y addr
que son ambas cadenas replicadas de la solicitud original.
El registro de foobar
, ya que ya está registrado, daría lugar a la siguiente respuesta:
{
"success": false,
"name":"foobar",
"addr":"0x29347542eb07159fdeadbeefae16243d152f6b7b"
}
Algunos enlaces
: implementación de referencia de NodeJS utilizada por
ns.jami.net
y haciendo consultas a un nodo de Ethereum.