Numele Protocolului serverului

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

Normele privind formattarea denumirii

Numele de utilizator sunt verificate de un regex pentru a asigura unele reguli privind formatul lor:

  • Lungimea trebuie să fie între 3 și 32 de caractere

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

Cer un nume

Acesta este principalul serviciu furnizat de un server de nume.

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.

În exemplul nostru, răspunsul JSON ar fi:

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

Corpul este un document JSON cu un atribut de șiră: error. Acest atribut este completat cu un mesaj de eroare care explică eroarea (și ar putea fi afișat în client în viitor).

În ceea ce privește punerea în aplicare a referinței, documentul returnat este:

{
    "error":"name not registred"
}

Cererea unei adrese

Acest serviciu este o căutare inversă. Cereți o adresă și un nume de utilizator este returnat dacă unul este înregistrat pe serverul de nume.

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.

Corpul este un document JSON cu un atribut de știre: name. Valoarea acestui câmp este numele înregistrat la această adresă

În exemplul nostru, răspunsul JSON ar fi:

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

Corpul este un document JSON cu un atribut de șiră: error. Acest atribut este completat cu un mesaj de eroare care explică eroarea (și ar putea fi afișat în client în viitor).

În ceea ce privește punerea în aplicare a referinței, documentul returnat este:

{
    "error":"address not registred"
}

Înregistrarea unui nume

Această parte a protocolului este utilizată pentru a înregistra o nouă pereche de nume/adresse.

Request register

O cerere de înregistrare a numelui foobar este o cerere POST cu /name/foobar ca URI. Atributul de titlu Content-type trebuie setat la application/json.

Corpul cererii este un document JSON cu 2 atribute de șir: addr și owner. addr conține identificatorul Jami prefixat cu 0x și owner este numele care trebuie înregistrat.

Un exemplu pentru foobar ar putea fi:

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

Corpul conține un document JSON cu 1 atribut boolean success setat la true.

Ca exemplu:

{
    "success":true
}

Încercările ulterioare de a consulta numele sau adresa ar trebui să aibă succes.

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.

Corpul este un document JSON cu 2 atribute: success care este un boolean și error care este un șir. success este setat la false și error este umplut cu un mesaj de eroare care explică eroarea (și ar putea fi afișat în client în viitor).

Pentru o formatizare invalidă a numelui de utilizator, corpul ar putea fi:

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

Corpul este un document JSON cu 3 atribute: success care este un set boolean de false, name și addr care sunt ambele șiruri replicate din cererea inițială.

Înregistrarea foobar, având în vedere că a fost deja înregistrată, ar duce la următorul răspuns:

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