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.

A nyilvános névkiszolgáló az ns.jami.net-címen található, és egy elosztott adatbázist használ háttérként. Egy másik megvalósítás bármilyen más adatbázist vagy címtárszolgáltatást használhat, így a névkiszolgáló-protokoll újrafelhasználható.

Ha saját névszolgáltatót futtat, a felhasználónev keresése a username@example.com formájában a username név keresését a névszolgáltatónál a example.com. (Nem szükséges hozzáadni a @ns.jami.net alapértelmezett névszolgáltatót.)

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.

Kérés

A foobar nevre vonatkozó kérés egy GET kérés, amelynek az URI-ként a /name/foobar szerepel.

Válasz (sikeres)

Ha a név megtalálható, a status kódú 200 OK válaszokat kell küldeni a kliensnek, amely a Content-type mezővel állítja ki a application/json.

A test egy JSON dokumentum, amely két sorbeli attribútumot tartalmaz: name és addr. name egyenlő a kért dokumentummal, és addr a Jami ID hatvancasú jelölése, amely a 0x-vel van előtüntetve.

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

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

Válasz (Nem talált)

Ha a név nem talált, a status kódú 404 Not Found válaszát a kliensnek kell küldeni a Content-type mezővel, amelyet a application/json-nek kell beállítani.

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.

Kérés

A ID jami:29347542eb07159f316577e1ae16243d152f6b7b GET kérés a /addr/29347542eb07159f316577e1ae16243d152f6b7b URI-ként.

Válasz (sikeres)

Ha a cím egy felhasználónevet felel meg, a status kódú 200 OK válaszokat a kliensnek kell küldeni a Content-type mezővel, amelyet a application/json-nek kell beállítani.

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"
}

Válasz (Nem talált)

Ha a cím nem talált, a status kódú 404 Not Found válaszát a kliensnek kell küldeni a Content-type mezővel, amelyet a application/json-nek kell beállítani.

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.

Kérés

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"
}

Válasz (sikeres)

Ha a név/cím pár sikeresen regisztrálódik, a status kódú 200 OK válaszokat kell küldeni a kliensnek, amely a Content-type mezővel állítja ki a 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.

Válasz (rossz kérés)

Ha a regisztráció nem valósulhat meg a kérelem hibája miatt (formátálás, hiányzó attribútum stb.), a status kódú 400 Bad Request válaszát a kliensnek kell küldeni a Content-type mezővel, amelyet a application/json-ként kell beállítani.

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"
}

Válasz (tiltott)

Ha a regisztráció nem valósulhat meg, mert a név már elvégezték, a status kódot 403 Forbidden-vel rendelkező válaszot kell küldeni a kliensnek, amely a Content-type mezővel állítja ki a application/json-ként.

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"
}