Izenaren zerbitzari protokoloa

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

Izen formateatzeari buruzko arauak

Erabiltzaileen izenak regex batek egiaztatzen ditu, formatuaz hitz egiteko arau batzuk ziurtatzeko:

  • Luzera 3 eta 32 karaktere artean egon behar du.

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

Izen bat eskatzen.

Izen zerbitzari batek ematen duen zerbitzu nagusia da.

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.

Gure adibidean, JSONren erantzuna izango litzateke:

{
    "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 dokumentu bat da eta hari lotutako atributu bat du: error. Atributu hau akats mezu batekin betetzen da, akatsaren azalpena azaltzen duena (eta etorkizunean bezeroan ikus daiteke).

Erreferentziazko gauzatzeari buruz, itzultzen den dokumentuak:

{
    "error":"name not registred"
}

Helbide bat bilatzen

Zerbitzu hau atzera begiratzen da. Helbide bat eskatzen duzu eta erabiltzaile izena itzultzen da izen zerbitzarian erregistratzen bada.

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 dokumentu bat da eta jatorri bateko atributu bat du: name.

Gure adibidean, JSONren erantzuna izango litzateke:

{
    "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 dokumentu bat da eta hari lotutako atributu bat du: error. Atributu hau akats mezu batekin betetzen da, akatsaren azalpena azaltzen duena (eta etorkizunean bezeroan ikus daiteke).

Erreferentziazko gauzatzeari buruz, itzultzen den dokumentuak:

{
    "error":"address not registred"
}

Izen bat erregistratzea

Protokoloaren zati hau izen/heli bikote berri bat erregistratzeko erabiltzen da. Erregistro publiko nagusian erabiltzen da, baina opzionala izan daiteke pertsonalizatutako martxan jartzean.

Request register

Izenaren erregistroa egiteko eskaera foobar da POST eskaera /name/foobar URI gisa.

Eskariaren gorputza JSON dokumentu bat da, bi string atributuekin: addr eta owner. addr Jami ID du izena izenaz betea.

foobar adibide bat izan daiteke:

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

Gorputzak JSON dokumentu bat du 1 boolean atributu success egia.

Adibidez:

{
    "success":true
}

Izen edo helbidea galdetzeko beste saiakera arrakastatsua izan beharko litzateke.

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.

JSON dokumentu bat da, bi ezaugarri dituena: success, bolea eta error, hari bat dena. success, false eta error izendatuta dago, eta akatsaren azalpena azaltzen duen akats mezu batekin betea dago (eta etorkizunean bezeroan erakutsi daiteke).

Erabiltzaile-izenaren formatua ez badabil, gorputza izan daiteke:

{
    "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 dokumentu bat da, 3 ezaugarri dituena: success, zeinak boolean multzo bat diren false, name eta addr, biak jatorrizko eskaeratik errepikatu diren hariak direnak.

Erregistratzeak, dagoeneko erregistratua dagoenez, ondorengo erantzun hau ekarriko luke:

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