Namn Serverprotokoll

Det protokoll som används av Jami för att fråga och registrera ett namn baseras på en HTTP [REST] (https://en.wikipedia.org/wiki/Representational_state_transfer) API som svarar på förfrågningar med JSON-dokument och vanliga HTTP-statuskoder.

Den offentliga nameservern är värd på ns.jami.net och använder en blockchain som sin backend.

Om du kör din egen nameserver, söker du efter ett användarnamn i form av username@example.com kommer du att leta efter namnet username med nameservern på example.com. (Det behövs inte lägga till @ns.jami.net för att använda standardnameservern.)

Regler för namnsformatering

Användarnamn kontrolleras av en regex för att säkerställa vissa regler om deras format:

  • Längden ska vara mellan 3 och 32 tecken

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

Fråga efter ett namn

Detta är den viktigaste tjänsten som tillhandahålls av en namnserver.

Förfrågan

En begäran om namn foobar är en GET begäran med /namn/foobar som URI.

Reaktion (framgång)

Om namnet hittas ska ett svar med statuskoden 200 OK skickas till kunden med ett Content-type fält som anges som application/json.

Den är ett JSON-dokument med 2 attribut: name och addr. name är lika med den begärda och addr är en hexadecimal representation av Jami ID med prefix med 0x.

I vårt exempel skulle svaret på JSON vara:

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

Svar (Fanns inte)

Om namnet inte hittas, ska ett svar med statuskoden 404 Not Found skickas till kunden med ett Content-type fält som anges som application/json.

Den är ett JSON-dokument med 1 strängattribut: error. Attributet fylles med ett felmeddelande som förklarar fel (och kan visas i klienten i framtiden).

När det gäller referensförslaget är det återlämnade dokumentet:

{
    "error":"name not registred"
}

Fråga om adress

Du frågar efter en adress och ett användarnamn returneras om ett är registrerat på namnservern.

Förfrågan

En begäran om ID jami:29347542eb07159f316577e1ae16243d152f6b7b är en GET begäran med /addr/29347542eb07159f316577e1ae16243d152f6b7b` som URI.

Reaktion (framgång)

Om adressen motsvarar ett användarnamn, måste ett svar med statuskoden 200 OK skickas till kunden med ett Content-type fält som anges som application/json.

Den här fältet är ett JSON-dokument med ett attribut med en rad: name.

I vårt exempel skulle svaret på JSON vara:

{
    "name":"foobar"
}

Svar (Fanns inte)

Om adressen inte hittas, ska ett svar med statuskoden 404 Not Found skickas till kunden med ett Content-type fält som anges som application/json.

Den är ett JSON-dokument med 1 strängattribut: error. Attributet fylles med ett felmeddelande som förklarar fel (och kan visas i klienten i framtiden).

När det gäller referensförslaget är det återlämnade dokumentet:

{
    "error":"address not registred"
}

Registrering av ett namn

Denna del av protokollet används för att registrera ett nytt namn/adresspar.

Förfrågan

En begäran om registrering av namnet foobar är en POST begäran med /namn/foobar som URI.

Den totala delen av begäran är ett JSON-dokument med två attribut: addr och owner. addr innehåller Jami ID med förfixet 0x och owner är det namn som ska registreras.

Ett exempel på foobar kan vara:

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

Reaktion (framgång)

Om namn/adressparet registreras med framgång måste ett svar med statuskoden 200 OK skickas till kunden med ett Content-type fält som anges som application/json.

Den innehåller ett JSON-dokument med 1 booleanattribut success som är inställd på true.

Som exempel:

{
    "success":true
}

Ytterligare försök att fråga om namn eller adress bör då lyckas.

Svar (Skad begäran)

Om registrering inte kan ske på grund av ett fel i begäran (formattning, saknade attribut etc.), måste ett svar med statuskoden 400 Bad Request skickas till kunden med ett Content-type fält som anges som application/json.

Den är ett JSON-dokument med 2 attribut: success som är en boolean och error som är en sträng. success är inställd på false och error är fylld med ett felmeddelande som förklarar fel (och kan visas i klienten i framtiden).

För en ogiltig formatering av användarnamnet kan kroppen vara:

{
    "success": false,
    "error": "invalid name"
}

Svar (förbud)

Om registreringen inte kan ske eftersom namnet redan har tagits, måste ett svar med statuskoden 403 Behörig skickas till kunden med ett Content-type fält som anges som application/json.

Den är ett JSON-dokument med 3 attribut: success som är ett booleansätt till false, name och addr som båda är strängar replikerade från den ursprungliga begäran.

Registrering av foobar, eftersom den redan är registrerad, skulle leda till följande svar:

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