что за API token?

[bogdan108]

В личном кабинете обнаружил ссылку Сгенерировать api токен

Там текст вида New api key: ah0lBsYAVn8VG9BHVpNz

Что это за токен и как им пользоваться?

[Slava]

Пока его можно только сгенерировать.
Я пишу rest api для DBL, по крайне мере получение листа для проверки в json.
Не стоит публиковать свой токен, это как пароль, сгенерируйте новый.

[bogdan108]

ключ изменил перед публикацией...

Сейчас пишу скрипт для автоматической отправки результатов проверки списка набором curl-запросов, но пока туго с этим:
- зайти на главную страницу, активировав сессию (ключ сессии прилетит от сервера в куках);
- с куками залогиниться (в куках должен быть валидный ключ сессии);
- с куками запросить лист (с валидным ключем сессии);
- проверить лист;
- отправить результаты с куками, в которых тот же самый ключ сессии, что был при отправке запроса списка.
Трудность только в том, что впервые с таким сталкиваюсь.

Условия задачи известны, потому задача решаема.
Только весь этот набор опреаций всё-равно будет выполять машина, так почему бы не упростить задачу до одностройчной команды "curl token %JSON_DATA% send-list-url"?

Хочу отправку результатов проверки через API/json. Какова вероятнось внерения?

[Slava]

Все возможно, но есть проблема со свободным временем, на реализацию интерфейса.
Сделаю, когда смогу.

[bogdan108]

Желаемые команды в API:

запрос: getUserStats
ответ: (rating, balance, nik, multiplier) # как в https://rejik.ru/cgi-bin/cabinet.cgi
пример ответа в формате json:

Код: Выделить всё

{"rating":307,"balance":170,"nik":"bogdan108","multiplier":1}

запрос: getListConfig
ответ: (sizes[],lists[]) # как в https://rejik.ru/cgi-bin/cabinet.cgi
- sizes[] = 10,20,30,40,50,60,70,80,90 # набор допустимых размеров списков;
- lists[] = buysell.urls, web-mail.urls, ... # доступные для обновления пользователем списки.
пример ответа в формате json:

Код: Выделить всё

{"sizes":["10","20","30","40","50","60","70","80","90","100"],"lists":["buysell.urls","web-mail.urls"]}

Теоретически, полные списки sizes и lists можно один раз загрузить при первом старте программы, сохранить в локальном кеше и проверять не чаще раза в месяц. Исключение для внеочередной проверки - явная инструкция в очередном ответе от сервера (вроде "WARN__NEED_UPDATE_CONFIG"). При использовании на стороне клиента, lists фильтровал бы я согласно условным правилам по величине рейтинга (если < 200 - то предоставлять выбор только из нескольких вариантов). Соответственно, было бы интересно почитать где-то о таких правилах формирования доступности списков пряио в описании к команде api.

[bogdan108]

Проблема: в базе есть несколько правил, которые там быть не должны.
Существующие варианты - можно обновить только reason. А мне необходимо обновить rule.

Например:

Тут лишний пробел вначале имени хоста:

<record id="983327">
<rule> xilisoft.com</rule>

Это вообще не url и не hostname:

<record id="981707">
<rule>1</rule>

Попытка добавить правило защитана. Но само правило - не url и не hostname.

<record id="983285">
<rule>123</rule>
<add>
<reason>123.ru</reason>
</add>

Варианты выхода из положения:
Вариант 0) проигнорировать (как бы не вошло в привычку...)
Вариант 1) попросить админа
Вариант 2) изменить самостоятельно

Предложение: добавить команды updateRule и removeRule в API/json (по возможности - добавить отдельную форму в личном кабинете).

* Команда removeRule(id) - удаление правила по его идентификатору.
Разрешено удалять только свои правила.
Ограничение: каждому пользователю 15 удалённых правил за последние 90 дней (позволит устранить последствия невнимательности, но не даст затроллить систему).

* Команда updateRule(id,rule,reason,answer) - обновить существующее правило по его идентификатору.
Разрешено обновлять только свои правила.
Обязательные аргументы: id.
Необязательные аргументы: rule, reason, answer.
Дополнительные условия: минимум один необязательный аргумент в запросе.
Ограничение: в отношении тех правил, которые затрагивают атрибут rule - 15 правил за последние 60 дней (обновление атрибутов answer/reason - без ограничений, или как там устроено сейчас).

* Форма изменения существующего правила в личном кабинете:
Указываем id правила. Нажимаем "Извлечь данные". Получаем форму с данными по записи с указанным id, в которой можем менять все поля. По нажатию "отправить" - новые правила отправляются на сервер.
Ограничения: разрешено загружать форму с данными по записи только 45 раз за календарный месяц (отчёт с 1-го по последнее число месяца).

* Дополнительные ограничения при добавлении/обновлении правила: проверять rule в листах типа "urls" на соответствие требованиям к hostname:
- допустимые символы: только буквы (в том силе русские, мультиязычные), цифры, "." (точка), "_" (нижнее подчёркивание) и "-" (минус);
- минимум 1 точка в rule;
- минимум 2 символа в имени домена;
- прочие ограничения (дополнительно - в rfc1035, 2.3.1. Предпочитаемый синтаксис имени)

[Slava]

Правило не обязательно должно быть урлом или хостнеймом, все немного сложнее.
Посмотрите форму пополнения листа, я дал Вам доступ на удаление по id.

[bogdan108]

Правило не обязательно должно быть урлом или хостнеймом, все немного сложнее.

На сколько понимаю я - смысл функционирования redirector - преобразование URI. Преобразование осуществляется только при совпадении полученного uri с одним из шаблонов, которые в rejik названы правилами (по существу - правило - это правило формирования шаблона для URI) . Т.е. rejik выполняет простой принцип - "совпало URI с шаблоном или не совпало". Шаблон может быть представлен в виде MATCH (точное совпадение части строки) или REGEXP. Для match применяется условие: неуказанные в правиле части URI принимаются как "все возможные варианты", атрибут hostname сравнивается только целиком (без частичного с овпадения), иерархическая часть и всё что за ней - сравнивается по принципу "частичное совпадение по началу строки".

Надеюсь, мы понимаем фильтрации rejik-ом одинаково.

Сейчас дошло, что redirector может по разному реагировать на "example.com", "http://example.com" и "http://example.com/".
В первом случае - заблокирует всю активность к указанному серверу.
Во втором - заблокирует обращение к серверу по http.
А в третьем - разрешит обратиться (установить соединение), но не даст загрузить страницу.
Однако, правила в списке urls для redirector нормализуются/разворачиваются в каноническую форму uri, т.е. правила "http://example.com" и "http://example.com/" для него должны быть равнозначны, поскольку браузер в обоих случаях запросит "http://example.com/" (со слешем в конце), а "http://example.com/" совпадает и с "http://example.com" по hostname (и далее сравнение прекращается), и c "http://example.com/" (тут тоже сравнение прекращается на hostname, поскольку первый символ "/" - это разделитель между hostname и path, т.е. path равен пустой с троке, а сравнение с пустой строкой не производится).

Я обосновал свою позицию, что "http://example.com" и "http://example.com/" в списках типа urls в одной категории - равнозначны.

Посмотрите форму пополнения листа, я дал Вам доступ на удаление по id.

Это ведь только к своим правилам? Не удалю случаем чужих?

[Slava]

Это ведь только к своим правилам? Не удалю случаем чужих?

Это было для всех. Убрал доступ.
Для удаления своих, добавьте тоже правило с ответом "нет" и оно не попадет в лист.

Позже, возможно, в api удаление своего действия по id сделаю.

[Slava]

Начал делать API, первый запрос:
https://rejik.ru/index_ru_8_11.html

[bogdan108]

Начал делать API, первый запрос:
https://rejik.ru/index_ru_8_11.html

У меня пожелание - внедрить систему обозначений для ответов сервера, отличных от нормального поведения.

Как сейчас.
Для систуации, когда token не принят системой, сервер отвечает с кодом, отличным от 200 и текстом в формате json:

Код: Выделить всё

{"Message" : "Bad api token format"}

Согласен - человеку читать и понимать такие строки легко. А вот я намучался обучать скрипт понимать подобные человеко-удобные строки в html-коде сраниц личного кабинета rejik-а. Приходится использовать regexp...

Как хочу.
Для систуации, когда token не принят системой, получить код ответа сервера, отличный от 200 (так же, как уже придумано), но в тексте ответа обнаружить:

Код: Выделить всё

{"err_code" : "ERR__API_TOKEN_FORMAT_INVALID"}

Здесь:
- "err_code" - тег, указывающий на наличие ошибки обработки запроса;
- "ERR__API_TOKEN_FORMAT_INVALID" - текстовый код ошибки обработки запроса.
Такая строка так же легко понимаема человеком, знакомым с английским языком. А если свести такие коды ошибок в один файл с парами значений "код ошибки" - "описание ошибки", то получится файл локализации системы (https://rejik.ru/api/v1/messages). Его легко перевести на разные языки (https://rejik.ru/api/v1/messages?lang=ru).
Если однажды, в строке, вроде "Bad api token format", разработчик api найдёт грамматическую ошибку и поменяет текст, то остальным пользователям API придётся испытать грусть от сломанного API..

Пример файла с перечнем кодов ошибок (https://rejik.ru/api/v1/messages?lang=en):

Код: Выделить всё

{
"ERR__API_TOKEN_FORMAT_INVALID" : "Bad api token format",
"ERR__API_TOKEN_INVALID" : "Api token not valid",
"MSG__RULE_REGISTERED" : "Rule registered to database",
"MSG__CHECKLIST_INCOMPLETE" : "Checklist incomplete"
}

В нём двойное подчеркивание разделяет непосредственно код состояния от уровня сообщения:
- ERR - error - ошибка при обработке запроса. Ошибки с таким уровнем - это ошибки взаимного понимания системой того, что система принимает от пользовательского приложения (например: все ошибки, произошедшие до этапа авторизации; ошибки самой системы (если недоступна база данных, с которой работает сервер, то выданная пользователю ошибка представляется мне именно в этом уровне); ошибка формата приянтых данных (сервер ожидает строку текста, а получил бинарные данные));
- WARN - warning - сообщение при нормальной обработке запроса, когда сервер понимает формат данных, полученных через API, даже частично разобрал что пользовательская программа от него хочет, но запрос неполный (например: не хватает каких-то обязательных входных параметров для запроса; среди дополнительных параметров какие-то имена параметров неизвестны; размер значения какого-то параметра превышает заданные пределы (если пользователь при добавлении правила введёт reason длиной в 10 тыс символов - то я бы предпочёл получит ошибку уровня WARNING, а не ERROR));
- MSG - message - сообщение при нормальной обработке запроса, когда сервер понимает, что говорит пользовательская программа, запрос корректен и выполнен

[Slava]

Поменять текст или добавить "err_code" к "Message" не сложно, хотя я не вижу большой разницы.
Что в API_TOKEN_FORMAT_INVALID что в "Bad api token format" можно допустить ошибку.
Если Вам так удобнее, добавлю.

Держать отдельный словарь для перевода из err_code в Message мне кажется сомнительным - это лишний запрос к api для расшифровки кода, а возможно и хуже, удвоение количества запросов, так как неизвестно, когда меняется словарь.
Проще сразу выдавать и "err_code" и "Message" в ответе.

Но что вы будете с ними делать?
В каком случае будете игнорировать Message и использовать err_code?
Разве что для перевода... хотя я не уверен, что он как-то нужен в api или в интерфейсе.
На мой взгляд достаточно ОК или не ОК, а если не ОК, то вот сообщение на английском.

Введение ERR, WARN и MSG дублируют код ответа, по этому мне кажутся лишними.
Как вы планируете обрабатывать двойственные ситуации, когда код 200 а в сообщении ERR или наоборот?

[Slava]

и на развитие:
Представьте, что вы написали, прошел год, немного изменилась логика в DBL и появился новый ответ:
{"err_code" : "PATAMUCHTO_GLADIOLUS"}
ему соответствует {"Message" : "GLADIOLUS!!!"}
А у вас такой ответ в программе не предусмотрен...

Если Вы сделали вывод "ошибка" и текст Message, то программа будет работать как раньше.
Если вы это как-то сложно обрабатываете, то нужно переписывать.

[bogdan108]

Держать отдельный словарь для перевода из err_code в Message мне кажется сомнительным - это лишний запрос к api для расшифровки кода, а возможно и хуже, удвоение количества запросов, так как неизвестно, когда меняется словарь.
Проще сразу выдавать и "err_code" и "Message" в ответе.

Назначение API в первую очередь - для связи пользовательской программы с серверной системой. А уж в исключительных случаях - для общения живого человека с системой. Из этой позиции и исхожу.

Список кодов ответов - это готовый справочник кодов состояний, обработку которых стороннему разработчику необходимо реализовать в своей программе, чтобы его программа могла максимально задействовала предложенный системой функционал. В сторонней программе не возникает вопрос "где брать словарь перевода?" - там словарь скачивается один раз при создании программы и по одному разу при очередном обновлении программы, но не при каждом API-запросе.

Пока система в разработке - API меняется - меняются и сообщения.
Как только API стабилизируется - расшифровка кода состояния будет лишней нагрузкой в ответе, так как высока вероятность, что текст расшифровки кода состояния на английском языке, до отображения живому человеку в русскоязычной программе не дойдёт (скорее всего - будет просто отброшен), а переводить на лету выражения из одного языка на другой в устоявшемся API - это как-то нерационально, проще и быстрее (для машинной обрабоки) взять перевод из готового справочника, заблоговременно подготовленного для нужного языка.

Если пойти дальше ради экономии трафика - можно даже заменить коды состояния числовыми значениями - но тогда живому человеку, решившему полезть в API - будет тяжело воспринимать такие сообщения сервера. Будет существенная нагрузка на сервер - тогда встанет вопрос на эту тему.

В моём представлении текстовые коды состояния - это тот самый баланс между размером трафика, машинным общением и человеческим пониманием ответов сервера.

[bogdan108]

и на развитие:
Представьте, что вы написали, прошел год, немного изменилась логика в DBL и появился новый ответ:
{"err_code" : "PATAMUCHTO_GLADIOLUS"}
ему соответствует {"Message" : "GLADIOLUS!!!"}
А у вас такой ответ в программе не предусмотрен...

Если Вы сделали вывод "ошибка" и текст Message, то программа будет работать как раньше.
Если вы это как-то сложно обрабатываете, то нужно переписывать.

Это сигнал обновить справочник кодов состояний...
Программа скачает (ОДИН РАЗ) обновлённый справочник по известному адресу, отобразит расшифровку неизвестного кода на языке из скачанного справочника, сохранит новый справочник для будущего использования как "дополнительный" и уведомит разработчика программы о факте появления изменений в API.

А если новый код только введён в систему, но ещё не обновлён справочник (как по мне, так вначале должен быть обновлён справочник, а затем - новые коды из справочника применяться на практике) - пользователь получит тот самый код "PATAMUCHTO_GLADIOLUS", который хоть в приближённом формате, да понятен разработчику программы (именно к нему свалятся жалобы пользователей программы на неизвестную ошибку).