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"
}
Een aantal links
gitlab:jami-nameservice: verwijzing NodeJS implementatie gebruikt door
ns.jami.net
en het vragen stellen van een Ethereum-knop.