Nimi Server-protokolli

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

Nimien muotoiluun liittyvät säännöt

Käyttäjänimiä tarkistaa regex, jotta voidaan varmistaa, että niiden muoto on varsin tiettyä:

  • Pitkäys on oltava 3-32 merkkiä

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

Kysyn nimeä

Tämä on nimispalvelin tarjoama pääpalvelu, jonka avulla saat Jami-tunnuksen, joka vastaa käyttäjänimestä.

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.

Esimerkkeessä JSON-vastaus olisi:

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

JSON-dokumentti on JSON-dokumentti, jossa on 1 sarjan ominaisuus: error. Tämä ominaisuus on täynnä virheen viestiä, joka selittää virheen (ja se voi näkyä asiakkaan kohdalla tulevaisuudessa).

Viite täytäntöönpanoon palautetun asiakirjan on:

{
    "error":"name not registred"
}

Osoitteen kysely

Tämä palvelu on käänteinen hakemus. Kysyt osoitteesta ja käyttäjänimi palautetaan, jos nimi on rekisteröity nimispalvelin.

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.

JSON-dokumentti on JSON-dokumentti, jossa on 1 sarjan ominaisuus: name. Tämän kentän arvo on tähän osoitteeseen rekisteröity nimi

Esimerkkeessä JSON-vastaus olisi:

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

JSON-dokumentti on JSON-dokumentti, jossa on 1 sarjan ominaisuus: error. Tämä ominaisuus on täynnä virheen viestiä, joka selittää virheen (ja se voi näkyä asiakkaan kohdalla tulevaisuudessa).

Viite täytäntöönpanoon palautetun asiakirjan on:

{
    "error":"address not registred"
}

Nimen rekisteröinti

Tätä protokollan osaa käytetään uuden nimik/osoitteen parin rekisteröintiin.

Request register

foobar nimen rekisteröintihakemus on POSThakemus, jossa /name/foobar on URI.

Hakemuksen kokonaisuus on JSON-asiakirja, jossa on kaksi sarjaa: addr ja owner. addr sisältää Jami ID:n, jossa on ennennätys 0x ja owner on rekisteröidyt nimi.

foobar:n esimerkki voisi olla:

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

Kehossa on JSON-asiakirja, jossa on 1 boolean-attribuutti success, joka on asetettu true.

Esimerkkinä:

{
    "success":true
}

Jälkimmäiset yritykset kysyä nimeä tai osoitetta olisivat sitten onnistuneet.

Response register (Bad request)

If the registration is unable to 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.

JSON-dokumentti on JSON-dokumentti, jossa on kaksi ominaisuutta: success, joka on booleaninen ja error, joka on sarja. success on asetettu false ja error on täynnä virheen viestiä, joka selittää virheen (ja se voi näkyä asiakkaan kohdalla tulevaisuudessa).

Käyttäjänimen väärän muotoilun osalta keho voi olla:

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

JSON-dokumentti on JSON-dokumentti, jossa on 3 ominaisuutta: success, joka on boolin asetus false, name ja addr, jotka ovat molemmat alkuperäisestä pyynnöstä toistettuja sarjoja.

Jos rekisteröinti on jo rekisteröity, se johtaa seuraaviin vastauksiin:

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