Нарича се протокол на сървъра

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.

Публичният сървър на имената е хостиран на ns.jami.net и използва блокчейн като своя обратен край.

Ако използвате свой собствен сървър за имена, търсейки потребителско име под формата username@example.com ще търсите името username с потребителския сървър на example.com. (Няма нужда да добавите @ns.jami.net, за да използвате дефолтния потребителски сървър.)

Правила за форматиране на имената

Потребителските имена се проверяват от регекс, за да се гарантира някои правила за формата им:

  • Дължина трябва да бъде между 3 и 32 символа

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

Искаме име

Това е основната услуга, която се предоставя от сървър на имена.

Заявление

Заявление за наименование foobar е заявление GET с /name/foobar като URI.

Отговор (успех)

Ако се намери името, отговор с код за състояние 200 OK трябва да бъде изпратен на клиента с поле Content-type зададено като application/json.

Тялото е JSON документ с 2 атрибута на веригата: name и addr. name е равно на исканото и addr е шестодецимално представяне на идентификатора Jami предписана с 0x.

В нашия пример отговорът на JSON ще бъде:

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

Отговор (Не е намерен)

Ако името не се намери, отговор с код за статус 404 Not Found трябва да бъде изпратен на клиента с поле Content-type зададено като application/json.

Тялото е JSON документ с 1 атрибут на редица: error. Този атрибут е изпълнен с съобщение за грешка, което обяснява грешката (и може да се показва в клиента в бъдеще).

За референтното изпълнение връщаният документ е:

{
    "error":"name not registred"
}

Поискане на адрес

Тази услуга е обратна търсене. Вие търсите адрес и потребителското име се връща, ако е регистриран на името сървър.

Заявление

Заявление за идентификационен идентификатор jami:29347542eb07159f316577e1ae16243d152f6b7b е заявление GET с /addr/29347542eb07159f316577e1ae16243d152f6b7b като URI.

Отговор (успех)

Ако адресът съответства на потребителско име, отговор с код за състояние 200 OK трябва да бъде изпратен на клиента с поле Content-type, зададено като application/json.

Тело е JSON документ с 1 атрибут на реже: name.

В нашия пример отговорът на JSON ще бъде:

{
    "name":"foobar"
}

Отговор (Не е намерен)

Ако адресът не бъде намерен, отговор с код за статус 404 Not Found трябва да бъде изпратен на клиента с поле Content-type зададено като application/json.

Тялото е JSON документ с 1 атрибут на редица: error. Този атрибут е изпълнен с съобщение за грешка, което обяснява грешката (и може да се показва в клиента в бъдеще).

За референтното изпълнение връщаният документ е:

{
    "error":"address not registred"
}

Регистриране на име

Тази част от протокола се използва за регистриране на нов двойка име/адрес.

Заявление

Заявление за регистрация на името foobar е заявление POST с /name/foobar като URI. Атрибутът заглавие Content-type трябва да бъде зададен на application/json.

Телата на искането е JSON документ с 2 атрибута на веригата: addr и owner. addr съдържа идентификатора Jami, предписана с 0x и owner е името, което трябва да бъде регистрирано.

Пример за foobar може да бъде:

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

Отговор (успех)

Ако двойката име/адрес е регистрирана успешно, отговор с код за статус 200 OK трябва да бъде изпратен на клиента с поле Content-type зададено като application/json.

Тело съдържа JSON документ с 1 булеански атрибут success, поставен на true.

Като пример:

{
    "success":true
}

След това следва да бъдат успешни допълнителните опити да се поиска името или адреса.

Отговор (лошо искане)

Ако регистрацията не може да бъде извършена поради грешка в искането (форматиране, липсващ атрибут и др.), отговор с код за състояние 400 Bad Request трябва да бъде изпратен на клиента с поле Content-type зададено като application/json.

Тялото е JSON документ с 2 атрибута: success, който е булеански и error, който е верига. success е зададен на false и error е изпълнен с съобщение за грешка, което обяснява грешката (и може да бъде показан в клиента в бъдеще).

За недействителен форматиране на потребителското име, тялото може да бъде:

{
    "success": false,
    "error": "invalid name"
}

Отговор (запретен)

Ако регистрацията не може да бъде извършена, защото името вече е взето, отговор с код за статус 403 Запретен трябва да бъде изпратен на клиента с поле Content-type зададено като application/json.

Тялото е JSON документ с 3 атрибута: success, което е буленски набор от false, name и addr, които са и двете репликирани от първоначалното искане.

Регистрирането на foobar, тъй като вече е регистрирано, би довело до следното откликване:

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