Naam Server protocol

Het protocol dat Jami gebruikt om een naam te vragen en te registreren, is gebaseerd op een HTTP [REST] (https://en.wikipedia.org/wiki/Representational_state_transfer) API die verzoeken beantwoordt met JSON-documenten en reguliere HTTP-statuscodes.

De publieke naamserver wordt gehost op ns.jami.net en gebruikt een blockchain als backend.

Als u uw eigen naamserver gebruikt, zal u een gebruikersnaam zoeken in de vorm van username@example.com en de naamserver username op example.com. (Uit de standaardnaamserver hoeft u geen @ns.jami.net toe te voegen.)

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.

Verzoek

Een verzoek om de naam foobar is een GET verzoek met /name/foobar als de URI.

Reactie (succes)

Als de naam wordt gevonden, moet een reactie met statuscode 200 OK naar de klant worden verzonden met een Content-type veld ingesteld als application/json.

Het lichaam is een JSON-document met 2 stringattribuuten: name en addr. name is gelijk aan de gevraagde en addr is een zesdecimale weergave van de Jami ID met voorvoegsel 0x.

In ons voorbeeld zou het JSON-antwoord zijn:

{
    "name":"foobar",
    "addr":"0x29347542eb07159f316577e1ae16243d152f6b7b"
}

Reactie (niet gevonden)

Als de naam niet wordt gevonden, moet een reactie met statuscode 404 Not Found naar de klant worden verzonden met een Content-type veld ingesteld als 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.

Verzoek

Een aanvraag voor de ID jami:29347542eb07159f316577e1ae16243d152f6b7b is een GET aanvraag met /addr/29347542eb07159f316577e1ae16243d152f6b7b` als de URI.

Reactie (succes)

Als het adres overeenkomt met een gebruikersnaam, moet een reactie met statuscode 200 OK naar de klant worden verzonden met een Content-type veld ingesteld als 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"
}

Reactie (niet gevonden)

Als het adres niet wordt gevonden, moet een antwoord met statuscode 404 Not Found naar de klant worden verzonden met een Content-type veld ingesteld als 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.

Verzoek

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

Reactie (succes)

Als het naam/adrespaar met succes is geregistreerd, moet een antwoord met statuscode 200 OK naar de klant worden verzonden met een Content-type veld ingesteld als 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.

Reactie (slechte verzoek)

Als de registratie niet kan worden bereikt wegens een fout in het verzoek (formatting, ontbrekende attribuut, enz.), moet een antwoord met statuscode 400 Bad Request naar de klant worden verzonden met een Content-type veld dat is ingesteld als 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"
}

Reactie (verboden)

Als de registratie niet kan worden bereikt omdat de naam al is genomen, moet een antwoord met statuscode 403 Forbidden naar de klant worden verzonden met een Content-type veld dat is ingesteld als 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"
}