API для провайдеров (ISP Go API)

ver.161024

Пользователь

[user_id] - идентификатор пользователя провайдера. Может содержать cимволы A-Z, a-z, 0-9 подчеркивание и тире.

Максимальная длинна 32 символа.

Создание пользователя

Новый пользователь создается при попытки создать для него какое-либо свойство: указать категории, присвоить ip.

Удаление пользователя

DELETE /users/[user_id]

Проверка пользователя на существование

HEAD /users/user1

В случае успеха возвращает код HTTP ответа 200. Если пользователь не найден – возвращает код HTTP ответа 404

Получение списка активных пользователей

GET /active_users/

возвращает ответ в формате

["geek", "bugtest", "hammer"]

Под активными подразумеваются пользователи, у которых есть хотя бы один IP-адрес.

Получение списка всех пользователей

GET /users

возвращает ответ в формате

["geek", "bugtest", "hammer"]

По-умолчанию возвращает первые 100 пользователей.

GET /users?start=100&stop=200

Параметры start и stop указывают на то, что надо вернуть пользователей начиная с 100 и до 200

Поиск пользователя

GET /search/user1

возвращает ответ в формате

["user1"]

ищет пользователя user1 по точному совпадению имени или ip адреса

Поиск возможен по ip или имени пользователя. В поиске можно использовать маски.

GET /search/129.168.0.*

Вернет всех пользователей, ip адрес которых начинается с 129.168.0.

GET /search/user*

Вернет всех пользователей, имя которых начинается с user

Получение информации по пользователю:

GET /users/[user_id]

возвращает ответ в формате

{"name": "[user_id]", "filter": [3, 4, 5, 6], "ip":
["192.168.5.6"], "whitelist": ["yandex.ru", "nic.ru"], "blacklist":
[], "status": "enabled", "safesearch": "off"}

Обновление информации о пользователе

PUT /users/[user_id]

Host: apiserver.hostname

Content-type: application/json

Content-Length: 131

{"name": "bugtest", "filter": [3, 4, 5, 6], "ip": ["192.168.5.6"],
"whitelist": ["yandex.ru", "nic.ru"], "blacklist": [], "status":
"enabled", "safesearch": "off"}}

Отключение фильтрации

Пользователь может отключить фильтрацию без сброса настроек

POST /users/[user_id]/status/disabled

Host: apiserver.hostname

Content-type: application/json

Включение фильтрации

POST /users/[user_id]/status/enabled

Host: apiserver.hostname

Content-type: application/json

Безопасный поиск

Если опция «Безопасный поиск» включена и пользователь делает запрос к поисковой системе, то в ответ он получает специальную страницу блокировки, которая осуществляет перенаправление на URL. URL безопасного поиска указывается в файле конфигурации. По-умолчанию это http://search.skydns.ru

Включение безопасного поиска

POST /users/[user_id]/safesearch/on

Host: apiserver.hostname

Content-type: application/json

Отключение безопасного поиска

POST /users/[user_id]/safesearch/off

Host: apiserver.hostname

Content-type: application/json

Адреса пользователя

Получение ip пользователя

GET /users/[user_id]/ip/

возвращает ответ в формате

["127.0.0.1"]

Добавление ip пользователя (происходит добавление к имеющимся)

POST /users/[user_id]/ip/

Host: apiserver.hostname

Content-type: application/json

Content-Length: 13

["127.0.0.1"]

или списка адресов

POST /users/[user_id]/ip/

Host: apiserver.hostname

Content-type: application/json

Content-Length: 26

["127.0.0.1", "127.0.0.2"]

Сохранение/обновление ip пользователя (происходит замещение имеющихся)

PUT /users/[user_id]/ip/

Host: apiserver.hostname

Content-type: application/json

Content-Length: 13

["127.0.0.1"]

или списка адресов

PUT /users/[user_id]/ip/

Host: apiserver.hostname

Content-type: application/json

Content-Length: 26

["127.0.0.1", "127.0.0.2"]

Удаление всех ip пользователя и отключение его от сервиса

DELETE /users/[user_id]/ip/

Удаление одного из ip пользователя

DELETE /users/[user_id]/ip/[127.0.0.1]

Общая информация

Получение группированного списка категорий с названиями и идентификаторами категорий

Для получения категорий на языке отличном от языка по-умолчанию необходимо добавить в запрос HTTP заголовок Accept-Language с указанием языка (например en_GB)

GET /categorygroups/

ответ в формате

[
    {
        "group" : "Общие",
        "categories" :
        {
            "3" : "Сайты, распространяющие вирусы",
            "4" : "Фишинг",
            ...
        }
    },
    {
        "group" : "Черные сайты",
        "categories" :
        {
            "6" : "Наркотики",
            ...
        }
    },
    ...
]

Получение списка категорий с названиями и идентификаторами категорий

Для получения категорий на языке отличном от языка по-умолчанию необходимо добавить в запрос HTTP заголовок Accept-Language с указанием языка (например en_GB)

GET /categories/

возвращает ответ в формате json

{"3":"Сайты, распространяющие вирусы","4":"Фишинг", …}

Получение категорий сайта

GET /site/login.vk.com

Пример ответа:

{"domain": "vk.com", "categories": [29]}

Здесь vk.com - это домен, который нашелся в нашей базе, а [29] - это список категорий (в данном случае состоящий из одной категории «социальные сети»). В дальнейшем могут добавляться новые поля.

Категории для блокировки

Получение списка категорий пользователя

GET /users/[user_id]/filter/

ответ в формате

[1,2,3]

Добавление категории в список пользователя

POST /users/[user_id]/filter/

Host: apiserver.hostname

Content-type: application/json

Content-Length: 5

[1,2]

Сохранение нового списка категорий пользователя

PUT /users/[user_id]/filter/

Host: apiserver.hostname

Content-type: application/json

Content-Length: 7

[1,2,3]

Отключение отдельной категории для пользователя

DELETE /users/[user_id]/filter/2

Отключение всех категорий для пользователя

DELETE /users/[user_id]/filter/

Черный список

Получение черного списка

GET /users/[user_id]/blacklist/

ответ в формате

["www.ya.ru"]

Добавление домена в черный список

POST /users/[user_id]/blacklist/

Host: apiserver.hostname

Content-type: application/json

Content-Length: 13

["www.ya.ru"]

Замена черного списка новым

PUT /users/[user_id]/blacklist/

Host: apiserver.hostname

Content-type: application/json

Content-Length: 13

["www.ya.ru"]

Удаление домена из черного списка

DELETE /users/[user_id]/blacklist/www.ya.ru

Удаление черного списка

DELETE /users/[user_id]/blacklist/

Установка опции «Работать только по белому списку»

Для работы пользователя в режиме «запрещено все, кроме того, что явно занесено в белый список», нужно занести корневой домен в черный список:

curl -X POST -d '["-"]' http://api.isp.ru/users/aep/blacklist/

Для удаления корневого домена:

curl -X DELETE http://api.isp.ru/users/aep/blacklist/-

Белый список

Получение белого списка

GET /users/[user_id]/whitelist/

ответ в формате

["www.ya.ru"]

Добавление домена в белый список

POST /users/[user_id]/whitelist/

Host: apiserver.hostname

Content-type: application/json

Content-Length: 13

["www.ya.ru"]

Замена белого списка новым

PUT /users/[user_id]/whitelist/

Host: apiserver.hostname

Content-type: application/json

Content-Length: 13

["www.ya.ru"]

Удаление домена из белого списка

DELETE /users/[user_id]/whitelist/www.ya.ru

Удаление белого списка

DELETE /users/[user_id]/whitelist

Глобальный черный список (имеет приоритет над списками пользователя)

Получение глобального черного списка

GET /blacklist/

ответ в формате

["www.ya.ru"]

Добавление домена в глобальный черный список

POST /blacklist/

Host: apiserver.hostname

Content-type: application/json

Content-Length: 13

["www.ya.ru"]

Замена глобального черного списка новым

PUT /blacklist/

Host: apiserver.hostname

Content-type: application/json

Content-Length: 13

["www.ya.ru"]

Удаление домена из глобального черного списка

DELETE /blacklist/www.ya.ru

Удаление глобального черного списка

DELETE /blacklist/

Установка опции «Работать только по глобальному белому списку»

Для работы пользователя в режиме «запрещено все, кроме того, что явно занесено в белый список», нужно занести корневой домен в черный список:

curl -X POST -d '["-"]' http://api.isp.ru/blacklist/

Для удаления корневого домена:

curl -X DELETE http://api.isp.ru/user/blacklist/-

Глобальный белый список (имеет приоритет над списками пользователя)

Получение глобального белого списка

GET /whitelist/

ответ в формате

["www.ya.ru"]

Добавление домена в глобальный белый список

POST /whitelist/

Host: apiserver.hostname

Content-type: application/json

Content-Length: 13

["www.ya.ru"]

Замена глобального белого списка новым

PUT /whitelist/

Host: apiserver.hostname

Content-type: application/json

Content-Length: 13

["www.ya.ru"]

Удаление домена из глобального белого списка

DELETE /whitelist/www.ya.ru

Удаление глобального белого списка

DELETE /whitelist/

Статистика

Активность пользователя по часам

Где [date_from], [date_to] даты в формате YYYY-MM-DD

GET /users/[user_id]/stat/activity/hour?from=[date_from]&to=[date_to]

Host: apiserver.hostname

Content-type: application/json

{"labels":["2016-06-29 14:00:00","2016-06-29
15:00:00"],"datasets":[{"label":"Requests","data":[375,275]},{"label":"Blocks","data":[13,0]}]}

Где labels — список временных интервалов, datasets — список объектов содержащих данные для графиков и легенды графиков, data — список значений соответствующих временным интервалам, label — название графика (Requests — кол-во запросов, Blocks — кол-во блокировок)

Активность пользователя по дням

Где [date_from], [date_to] даты в формате YYYY-MM-DD

GET /users/[user_id]/stat/activity/day?from=[date_from]&to=[date_to]

Host: apiserver.hostname

Content-type: application/json

{"labels":["2016-06-29","2016-06-30"],"datasets":[{"label":"Requests","data":[5770,
3456]},{"label":"Blocks","data":[8, 9]}]}

Где labels — список временных интервалов, datasets — список объектов содержащих данные для графиков и легенды графиков, data — список значений соответствующих временным интервалам, label — название графика (Requests — кол-во запросов, Blocks — кол-во блокировок)

Домены

GET /users/[user_id]/stat/domains/[filter]?from=[date_from]&to=[date_to]

Host: apiserver.hostname

Content-type: application/json

{"labels":["example.com","google.com","asdfg.com"],"datasets":[{"label":"Requests","data":[630,474,290]},{"label":"NXdomain","data":[0,0,290]},{"label":"Blocks","data":[630,0,0]}]}

Где [date_from], [date_to] даты в формате YYYY-MM-DD

[filter] может принимать значения all (возращает все домены), www (возращает только все домены, которые начинаются с www) labels — список доменов, datasets — наборы данных, data — список значений соответствующих каждому домену, label — название графика (Requests — кол-во запросов, Blocks — кол-во блокировок, NXdomain — кол-во ответов домен не существует)

Детальная

GET /users/[user_id]/stat/detail?from=[date_from]&to=[date_to]

Host: apiserver.hostname

Content-type: application/json

{"timestamps":["2016-06-29 15:00:00","2016-06-29
16:00:00"],"reports":[{"labels":["clients4.google.com","www.google.ru"],"cats":[[48,251],[48],"datasets":[{"label":"Requests","data":[29,20]},{"label":"NXdomain","data":[0,0]},{"label":"Blocks","data":[0,0]}]},{"labels":["live.github.com","lb._dns-sd._udp.0.0.200.10.in-addr.arpa","ssl.gstatic.com"],"cats":[[2],[2],[2]],"datasets":[{"label":"Requests","data":[73,48,48]},{"label":"NXdomain","data":[0,48,0]},{"label":"Blocks","data":[0,0,0]}]}]}

Где [date_from], [date_to] даты в формате YYYY-MM-DD

timestamps — список временных интервалов reports — список отчетов соответствующих временным интервалам labels — список доменов cats — списки категорий для доменов datasets — наборы данных data — список значений соответствующих каждому домену label — название графика (Requests — кол-во запросов, Blocks — кол-во блокировок, NXdomain — кол-во ответов домен не существует)

Статистика без агрегации

Полная статистика пользователя за последний час. Обновляется каждые пять минут.

GET /users/[user_id]/stat/raw

Host: apiserver.hostname

Content-type: application/json

{"fields":["created","nxdomain","address","host","blockedhost","reasom","cats","blockedcats"],"data":[["2016-07-11
17:50:26","0","10.200.1.88","www.tns-counter.ru","www.tns-counter.ru","4",[2],[0]],["2016-07-11
17:50:26","0","10.200.1.88","www.tns-counter.ru","www.tns-counter.ru","4",[2],[0]]]}

Коды ответов

400 Bad Request - Запрос сделан некорректно

404 Resource is not found - Ресурс не существует

500 Internal server error - Внутренняя ошибка сервера