Névkiszolgáló-protokoll

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

A névformázási szabályok

A felhasználói nevet egy regex ellenőrzi, hogy bizonyos szabályokat biztosítson a formájukról:

  • A hosszúság 3 és 32 karakter között kell lennie

  • Ezeknek a karaktereknek alfanumerikusnak kell lenniük, és a kötőjelet - is elfogadni kell.

Kérdezem a nevét

Ez a fő szolgáltatás, amelyet egy névszolgáló nyújt, lehetővé teszi a felhasználónevnek megfelelő Jami ID-t.

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.

A példánkban a JSON válasz:

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

A test egy JSON dokumentum, amelynek 1 nyerses attribútumja: error. Ez az attribútum egy hibaüzenettel van töltve, amely megmagyarázza a hibát (és a jövőben megjeleníthető a kliensben).

A referenciamegállapításról a visszaküldött dokumentum:

{
    "error":"name not registred"
}

Adszolút keresés

Ez a szolgáltatás egy fordított keresés. Ön keres egy címet és egy felhasználónev visszakerül, ha egy be van regisztrálva a névszolgálón.

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.

A test egy JSON dokumentum, amelynek 1 vonalbeli attribútumja: name. Ez a mező értéke a címre bejegyzett név

A példánkban a JSON válasz:

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

A test egy JSON dokumentum, amelynek 1 nyerses attribútumja: error. Ez az attribútum egy hibaüzenettel van töltve, amely megmagyarázza a hibát (és a jövőben megjeleníthető a kliensben).

A referenciamegállapításról a visszaküldött dokumentum:

{
    "error":"address not registred"
}

Név bejegyeztetése

A protokoll ezen része egy új név/cím pár regisztrálására szolgál.

Request register

A foobar nev bejegyzésére irányuló kérés egy POST kérés, amely a /name/foobar URI-címként történik.

A kérés szervének két vonalbeli attribútumú JSON dokumentuma van: addr és owner. addr tartalmazza a Jami ID-t, amelyet a 0x és owner jelölnek be.

A foobar példája lehet:

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

A test tartalmaz egy JSON dokumentumot, amelynek 1 boolean attribútumja success állítva true.

Például:

{
    "success":true
}

A név vagy cím feltárására irányuló további kísérleteknek sikeresek kell lenniük.

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.

A test egy JSON dokumentum, amely két attribútummal rendelkezik: success, ami booleán és error, ami egy nyoma. success a false és error-re állítjuk be, és egy hibaüzenettel töltjük be, amely megmagyarázza a hibát (és a jövőben megjeleníthető a kliensben).

A felhasználói név nem megfelelő formázása esetén a test lehet:

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

A test egy JSON dokumentum, amelynek 3 attribútumja van: success, amely a boolean false, name és addr, amelyek mindkét szúrát az eredeti kérelemből replikálják.

A foobar nyilvántartásba vétel a következő válaszhoz vezetne, ha már nyilvántartásba vették:

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