Naam Server protocol

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

Regels inzake het opmaken van namen

Gebruikersnamen worden door een regex gecontroleerd om bepaalde regels over hun formaat te waarborgen:

  • Lengte tussen 3 en 32 tekens

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

Een naam vragen

Dit is de belangrijkste dienst die wordt aangeboden door een naamserver. Het maakt het mogelijk om de Jami ID te krijgen die overeenkomt met een gebruikersnaam.

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.

In ons voorbeeld zou het JSON-antwoord zijn:

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

Het lichaam is een JSON-document met 1 stringattribut: error. Dit attribut wordt gevuld met een foutmelding die de fout verklaart (en in de toekomst in de client kan worden weergegeven).

Bij de referentieprijstelling is het teruggestuurd document:

{
    "error":"name not registred"
}

Een adres zoeken

Deze service is een omgekeerde zoekopdracht. Je vraagt naar een adres en een gebruikersnaam wordt teruggestuurd als er een is geregistreerd op de naamserver.

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.

Het lichaam is een JSON-document met 1 stringattribut: name. De waarde van dit veld is de naam die is geregistreerd op dit adres

In ons voorbeeld zou het JSON-antwoord zijn:

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

Het lichaam is een JSON-document met 1 stringattribut: error. Dit attribut wordt gevuld met een foutmelding die de fout verklaart (en in de toekomst in de client kan worden weergegeven).

Bij de referentieprijstelling is het teruggestuurd document:

{
    "error":"address not registred"
}

Registratie van een naam

Dit gedeelte van het protocol wordt gebruikt om een nieuw naam/adrespaar te registreren. Het wordt gebruikt in het hoofd openbaar register, maar kan opsioneel zijn bij een aangepaste implementatie.

Request register

Een aanvraag om de naam foobar te registreren is een POST aanvraag met /name/foobar als URI. Het headerattribut Content-type moet worden ingesteld op application/json.

Het lichaam van het verzoek is een JSON-document met 2 stringsattributen: addr en owner. addr bevat de Jami ID met voorvoegsel 0x en owner is de naam die moet worden geregistreerd.

Een voorbeeld van foobar zou kunnen zijn:

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

Het lichaam bevat een JSON-document met 1 boolean-attribut success ingesteld op true.

Als voorbeeld:

{
    "success":true
}

Vervolgens moeten verdere pogingen om de naam of het adres te vragen succesvol zijn.

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.

Het lichaam is een JSON-document met 2 attributen: success die een boolean is en error die een string is. success is ingesteld op false en error is gevuld met een foutbericht dat de fout verklaart (en in de toekomst in de cliënt kan worden weergegeven).

Voor een ongeldige opmaak van de gebruikersnaam kan het lichaam:

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

Het lichaam is een JSON-document met 3 attributen: success, een boolean set van false, name en addr, die beide stringen zijn gerepliceerd van het oorspronkelijke verzoek.

Het registreren van foobar, aangezien het reeds geregistreerd is, zou leiden tot de volgende reactie:

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