Nomo Servilo protokolo

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

Reguloj pri nomformatado

Uzanumoj estas kontrolitaj de regex por certigi kelkajn regulojn pri ilia formato:

  • Longo devas esti inter 3 kaj 32 karakteroj

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

Demando pri nomo

Ĉi tiu estas la ĉefa servo disponigita de nomo-servilo. Ĝi ebligas akiri la identigon de Jami, kiu egalrilatas al uzantnomo.

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.

En nia ekzemplo, la respondo de JSON estus:

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

La korpo estas JSON-dokumento kun 1 strio atributo: error. Tiu atributo estas plenigita kun erara mesaĝo kiu klarigas la eraron (kaj povus esti montrita en la kliento en la estonteco).

Pri la referenca efektivigo, la redonita dokumento estas:

{
    "error":"name not registred"
}

Serĉante adreson

Ĉi tiu servo estas inversa serĉado. Vi demandas pri adreso kaj uzantnomo estas redonita se unu estas registrita en la nomo servilo.

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.

La korpo estas JSON-dokumentoj kun 1 strinka atributo: name. La valoro de tiu kampo estas la nomo registrita al tiu adreso

En nia ekzemplo, la respondo de JSON estus:

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

La korpo estas JSON-dokumento kun 1 strio atributo: error. Tiu atributo estas plenigita kun erara mesaĝo kiu klarigas la eraron (kaj povus esti montrita en la kliento en la estonteco).

Pri la referenca efektivigo, la redonita dokumento estas:

{
    "error":"address not registred"
}

Registri nomon

Tiu parto de la protokolo estas uzata por registri novan nomon/adreson paron. Ĝi estas uzata en la ĉefa publika registro sed povas esti laŭvola en laŭmoda efektivigo.

Request register

Peto por registri la nomon foobar estas POST peto kun /nome/foobar kiel la URI. La intesta atributo Content-type devas esti metita al application/json.

La korpo de la peto estas JSON-dokumenton kun 2 strio atributoj: addr kaj owner. addr enhavas la Jami ID prefiksita kun 0x kaj owner estas la nomo por esti registrita.

Ekzemplo por foobar povus esti:

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

La korpo enhavas JSON-dokumenton kun 1 boolean atributo success metita al true.

Ekzemple:

{
    "success":true
}

Pliaj provoj por demandi la nomon aŭ adreson devus tiam esti sukcesaj.

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.

La korpo estas JSON-dokumento kun 2 atributoj: success kiu estas buola kaj error kiu estas ŝnuro. success estas metita al false kaj error estas plenigita per erara mesaĝo kiu klarigas la eraron (kaj povus esti montrita en la kliento en la estonteco).

Por malĝusta formatado de la uzantnomo, la korpo povus esti:

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

La korpo estas JSON-dokumento kun 3 atributoj: success kiu estas buola aro al false, name kaj addr kiuj estas ambaŭ ŝnuroj replikitaj de la origina peto.

Registrado foobar, kiam ĝi jam estas registrita, kondukus al la sekva respondo:

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