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