Navne Server protokol

Den protokol, som Jami bruger til at spørge og registrere et navn, er baseret på en HTTP [REST] (https://en.wikipedia.org/wiki/Representational_state_transfer) API, der besvarer anmodninger med JSON-dokumenter og almindelige HTTP-statuskoder.

Den offentlige navneserver er hostet på ns.jami.net og bruger en blockchain som sin backend. En anden implementering kan bruge enhver anden database eller katalogtjeneste, der gør navneserverprotokollen genbrugbar.

Hvis du kører din egen navneserver, søger du efter et brugernavn i form af username@example.com og du søger efter navnet username med navneserveren på example.com. (Der er ikke behov for at tilføje @ns.jami.net for at bruge standardnavneserveren.)

Regler for navneformatting

Brugernavne kontrolleres af en regex for at sikre nogle regler om deres format:

  • Længden skal være mellem 3 og 32 tegn

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

Spørgsmål om et navn

Dette er den vigtigste tjeneste, der leveres af en navneserver. Det gør det muligt at få Jami ID svarende til et brugernavn.

Anmodning

En anmodning om navnet foobar er en GET anmodning med /name/foobar som URI.

Reaktion (succes)

Hvis navnet findes, skal et svar med statuskode 200 OK sendes til kunden med et Content-type felt, der er indstillet som application/json.

Den er et JSON-dokument med 2 strengattributter: name og addr. name er lig med den anmodede og addr er en seksedesimal repræsentation af Jami ID præfixeret med 0x.

I vores eksempel ville svaret på JSON være:

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

Svar (ikke fundet)

Hvis navnet ikke findes, skal et svar med statuskode 404 Not Find sendes til kunden med et Content-type felt angivet som application/json.

Den er et JSON-dokument med 1 stregattribut: error. Dette atribut er fyldt med en fejlmeddelelse, der forklarer fejlen (og kan vises i klienten i fremtiden).

I forbindelse med referenceret er det returnerede dokument:

{
    "error":"name not registred"
}

Spørgsmål om adresse

Denne tjeneste er en omvendt søgning. Du spørger efter en adresse og et brugernavn returneres, hvis et er registreret på navneserveren.

Anmodning

En anmodning om ID jami:29347542eb07159f316577e1ae16243d152f6b7b er en GET anmodning med /addr/29347542eb07159f316577e1ae16243d152f6b7b` som URI.

Reaktion (succes)

Hvis adressen svarer til et brugernavn, skal et svar med statuskode 200 OK sendes til kunden med et Content-type felt angivet som application/json.

Den er et JSON-dokument med 1 strengattribut: name. Værdien af dette felt er navnet registreret på denne adresse

I vores eksempel ville svaret på JSON være:

{
    "name":"foobar"
}

Svar (ikke fundet)

Hvis adressen ikke findes, skal et svar med statuskode 404 Not Find sendes til kunden med et Content-type felt angivet som application/json.

Den er et JSON-dokument med 1 stregattribut: error. Dette atribut er fyldt med en fejlmeddelelse, der forklarer fejlen (og kan vises i klienten i fremtiden).

I forbindelse med referenceret er det returnerede dokument:

{
    "error":"address not registred"
}

Registrering af et navn

Denne del af protokollen bruges til at registrere et nyt navn/adresspar.

Anmodning

En anmodning om registrering af navnet foobar er en POST anmodning med /name/foobar som URI. Overskriften atributten Content-type skal indsættes til application/json.

Anmodningens legeme er et JSON-dokument med 2 strengattributter: addr og owner. addr indeholder Jami ID med forkortelse 0x og owner er det navn, der skal registreres.

Et eksempel på foobar kan være:

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

Reaktion (succes)

Hvis navnet/adressparet registreres med succes, skal et svar med statuskode 200 OK sendes til kunden med et Content-type felt angittet som application/json.

Kroppen indeholder et JSON-dokument med 1 boolean-attribut success indstillet på true.

Som eksempel:

{
    "success":true
}

Der bør derefter gøres yderligere forsøg på at søge efter navnet eller adressen.

Svar (Udvillig anmodning)

Hvis registreringen ikke kan opnås på grund af en fejl i anmodningen (formattning, manglende atributt osv.), skal et svar med statuskode 400 Bad Request sendes til kunden med et Content-type felt indstillet som application/json.

Den er et JSON-dokument med 2 attributter: success, som er en boolean og error, som er en streng. success er indstillet på false og error er fyldt med en fejlmeddelelse, der forklarer fejlen (og kan vises i klienten i fremtiden).

For en ugyldig formatering af brugernavnet kan det være:

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

Svar (forbudt)

Hvis registreringen ikke kan opnås, fordi navnet allerede er taget, skal et svar med statuskode 403 Forboden sendes til kunden med et Content-type felt angittet som application/json.

Den er et JSON-dokument med 3 attributter: success, som er et booleansk sæt til false, name og addr, som begge er strengene replikeret fra den oprindelige anmodning.

Registrering af foobar, når den allerede er registreret, vil føre til følgende svar:

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