Старый API после некоторых доработок потерял совместимость, поэтому мы решили выпустить вторую версию.
Рекомендуем использовать эту версию для написания запросов.
Формат дат для параметров запросов:
{code}
%Y-%m-%d %H:%M:%S
{code}
{code}
%Y-%m-%d
{code}
Отличия от старой версии:
* Новый адрес для запросов: http://<ip>:8082/rest_api/v2/
* Вместо передачи параметров в GET, перешли на POST
* Убрали из вывода результаты промежуточных вызовов (method1, method2,..), оставили только result
* Соответственно, немного поменялся схема вывода (см. соответствующий раздел)
* Модель указывается в url напрямую, например: http://<ip>:8082/rest_api/v2/Abonents/
* Атрибут запроса fields теперь не нужно маркировать номером метода. Он будет применяться к последнему объекту (возвращенному последним методом)
* Документацию (пока что только перечень доступных полей для запроса) можно посмотреть, пройдя браузером по ссылке http://<ip>:8082/rest_api/v2/
* Теперь можно в fields запрашивать вывод объектов по ссылкам (fk, m2m), обратным ссылкам и выводить property объектов, а также выводить конкретные поля этих объектов. Глубина запроса не ограничена, разделитель - двойное подчеркивание. *Внимание\! Django не объединяет запрос по обратной ссылке в один, поэтому он может выполняться заметно дольше для большого кол-ва объектов (например, если запросить все учетные записи у всех абонентов - будет 1 запрос для абонентов и по запросу на каждого абонента для получения его учетных записей)*
h3. Схема результата:
*Формат ответа:*
{code}
{"call": "/rest_api/v2/<model_name>/", "result": [<объект>, ...]}
{code}
тип поля result будет меняться в соответствии с данными (список для перечня объектов (objects.filter), словарь для 1 объекта (objects.get), значение метода при вызове метода и.т.д).
*Формат ошибки:*
{code}
{"call": "/rest_api/v2/<model_name>/", "error": "..."}
{code}
если в результате есть не пустое поле error, то значит запрос завершился неуспешно
*Формат объекта:*
{code}
{"pk": <id>, "model": "<model>", "fields": {"<field>": <value>, ...}
{code}
Если поле является ссылкой fk (например поле tarif у модели Abonents), то объект тарифа можно получить, задав fields=\["tarif"\], а pk тарифа, задав fields=\["tarif_id"\], например:
{code}
{"pk": <id>, "model": "Abonents", "fields": {"tarif": {"pk": <id тарифа>, "model": "Tarif", "fields": {<поля тарифа>}, "tarif_id": <id тарифа>}
{code}
Также, можно вывести только определенные поля тарифа через двойное подчеркивание: fields=\["tarif__name"\]:
{code}
{"pk": <id>, "model": "Abonents", "fields": {"tarif": {"pk": <id тарифа>, "model": "Tarif", "fields": {"name": <имя тарифа>}, "tarif_id": <id тарифа>}
{code}
Еще пример. Запрос ip адресов всех учетных записей абонента fields=\["abonent_id_users__ip"\]:
{code}
{"pk": <id>, "model": "Abonents", "fields": {"abonent_id_users": [{"pk": <id учетной записи>, "model": "Users", "fields": {"ip": "<ip>"}}, ...]}}
{code}
h3. Формирование запросов:
{code}
curl -XPOST -d 'method1=objects.all&arg1={}&fields=["tarif_id","tarif","abonent_id_users__ip","attr","child_folders_count"]' http://<ip>:8082/rest_api/v2/Abonents/ -D -
curl -XPOST -d 'method1=objects.all&arg1={}&fields=["tarif_id","tarif__name","tarif__reserve_plan","abonent_id_users__ip","attr","child_folders_count"]' http://<ip>:8082/rest_api/v2/Abonents/ -D -
{code}
h4. Для получения документации по методам
Вызовите в браузере http://<ip>:8082/rest_api/v2/ и выберите интересующую модель.
Например демо:
[http://195.64.222.86:8087/rest_api/v2/]
h3. Примеры:
Готовые примеры работы с API с помощью Python вы можете посмотреть здесь:
[github|https://github.com/carbonsoft/rest_api_example]
*Пример 1. Вывести абонентов, у которых есть учетная запись с ip = 127.1.2.3:*
{code}
curl -XPOST -d 'method1=objects.filter&arg1={"abonent_id_users__ip":"127.1.2.3"}' http://<ip>:8082/rest_api/v2/Abonents/ -D -
{code}
*или количество таких абонентов:*
{code}
curl -XPOST -d 'method1=objects.filter&arg1={"abonent_id_users__ip":"127.1.2.3"}&method2=count&arg2={}' http://<ip>:8082/rest_api/v2/Abonents/ -D -
{code}
*Пример 2. Установить абоненту с id = 45 номер квартиры 3:*
{code}
curl -XPOST 'http://<ip>:8082/rest_api/v2/Abonents/' --data 'method1=objects.get&arg1={"id":"45"}&method2=set&arg2={"a_home_number":"3"}&method3=save&arg3={}';
{code}
*Пример 3. Подключение услуги id=532 абоненту с номером договора BILL0000021*
{code}
curl -XPOST -d 'http://<ip>:8082/rest_api/v2/Abonents/' --data 'method1=objects.get&arg1={"contract_number":"BILL0000021"}&method2=add_service&arg2={"usluga_id":532}'
{code}
*Пример 4. Сколько абоненту с номером договора 1005633 нужно заплатить что проработать до 2016-10-20*
{code}
curl -XPOST -d 'method1=objects.get&arg1={"contract_number":"1005633"}&method2=get_credit_for&arg2={"end_credit_date":"2016-10-20"}' http://169.1.80.82:8082/rest_api/v2/Abonents/
{code}
*Пример 5. Выполнение отчёта 1003 с параметром phone="+79222222222"*
{code}
curl -XPOST -d 'method1=objects.get&arg1={"id":1003}&method2=get_data&arg2={"phone":"+79222222222"}' http://169.1.80.82:8082/rest_api/v2/AdminCustomReports/ -D -
{code}
*Пример 6. По абоненту с id=1383 вывести значение реквизита с id=26*
{code}
curl -XPOST -d 'method1=objects.filter&arg1={"abonent":"1383", "attribute":"26"}' http://<ip-биллинга>:8082/rest_api/v2/AttributeValues/ -D -
{code}
*Пример 7. Пример создания абонента с именем abonent, в папке 1 с тарифом с id 1*
{code}
def create_abonent(self, **kwargs):
params = {
'url': '(billing_url)/Abonents/'.format(self.api_url),
'method1': 'objects.create',
'arg1': {"name": "abonent", '"parent_id": 1,"tarif_id": 1}.
}
return self.get_api_result(self.post_request(**params))
{code}
*Пример 8. Установить абоненту с id 1321 тариф с именем Тестовый*
1. Получаем id тарифа по имени
{code}
curl -XPOST -d 'method1=objects.get&arg1={"name":"Тестовый"}' http://<ip-биллинга>:8082/rest_api/v2/tarif/ -D -
{code}
В поле pk получаем id тарифа, в данном случае 1118
2. Устанавливаем тариф абоненту по id
{code}
curl -XPOST -d 'method1=objects.get&arg1={"id":"1321"}&method2=set&arg2={"tarif_id":"1118"}&method3=save&arg3={}' http://<ip-биллинга>:8082/rest_api/v2/Abonents/ -D -
{code}
*Пример 9. Установить абоненту с номером учетной записи 1361 коммутатор с IP 1.1.1.1*
1. Получаем id коммутатора по IP
{code}
curl -XPOST -d 'method1=objects.get&arg1={"ip":"1.1.1.1"}' http://<ip-биллинга>:8082/rest_api/v2/Switch/ -D -
{code}
В поле pk получаем id коммутатора, в данном случае 1113
2. Устанавливаем коммутатор в учетную запись по id
{code}
curl -XPOST -d 'method1=objects.get&arg1={"id":"1361"}&method2=set&arg2={"switch_id":"1113"}&method3=save&arg3={}' http://<ip-биллинга>:8082/rest_api/v2/Users/ -D -
{code}
*Пример 10. Установить абоненту с номером учетной записи 1361 vlan 8*
{code}
curl -XPOST -d 'method1=objects.get&arg1={"id":"1361"}&method2=set&arg2={"router_vlan":"8"}&method3=save&arg3={}' http://<ip-биллинга>:8082/rest_api/v2/Users/ -D -
{code}
*Пример 11. Установить абоненту с номером учетной записи 1361 mac-адрес 00:AA:CC:11:44:88*
{code}
curl -XPOST -d 'method1=objects.get&arg1={"id":"1361"}&method2=set&arg2={"mac":"00:AA:CC:11:44:88"}&method3=save&arg3={}' http://<ip-биллинга>:8082/rest_api/v2/Users/ -D -
{code}
*Пример 12. Установить абоненту с номером учетной записи 1361 галочку opt82*
{code}
curl -XPOST -d 'method1=objects.get&arg1={"id":"1361"}&method2=set&arg2={"opt82":"1"}&method3=save&arg3={}' http://10.90.180.180:8082/rest_api/v2/Users/ -D -
{code}
*Пример 13. Установить абоненту с номером учетной записи 1361 порт номер 8 коммутатора 2.2.2.2*
1. Получаем id коммутатора по IP
{code}
curl -XPOST -d 'method1=objects.get&arg1={"ip":"2.2.2.2"}' http://<ip-биллинга>:8082/rest_api/v2/Switch/ -D -
{code}
В поле pk получаем id коммутатора, в данном случае 1114
2. Получаем id порта по его номеру
{code}
curl -XPOST -d 'method1=objects.get&arg1={"switch_id":"1114","num":"8"}' http://<ip-биллинга>:8082/rest_api/v2/SwitchPorts/ -D -
{code}
В поле pk получаем id порта коммутатора, в данном случае 1168
3. Устанавливаем порт в учетной записи по id порта из БД
{code}
curl -XPOST -d 'method1=objects.get&arg1={"id":"1361"}&method2=set&arg2={"switch_p":"1168"}&method3=save&arg3={}' http://<ip-биллинга>:8082/rest_api/v2/Users/ -D -
{code}
Рекомендуем использовать эту версию для написания запросов.
Формат дат для параметров запросов:
{code}
%Y-%m-%d %H:%M:%S
{code}
{code}
%Y-%m-%d
{code}
Отличия от старой версии:
* Новый адрес для запросов: http://<ip>:8082/rest_api/v2/
* Вместо передачи параметров в GET, перешли на POST
* Убрали из вывода результаты промежуточных вызовов (method1, method2,..), оставили только result
* Соответственно, немного поменялся схема вывода (см. соответствующий раздел)
* Модель указывается в url напрямую, например: http://<ip>:8082/rest_api/v2/Abonents/
* Атрибут запроса fields теперь не нужно маркировать номером метода. Он будет применяться к последнему объекту (возвращенному последним методом)
* Документацию (пока что только перечень доступных полей для запроса) можно посмотреть, пройдя браузером по ссылке http://<ip>:8082/rest_api/v2/
* Теперь можно в fields запрашивать вывод объектов по ссылкам (fk, m2m), обратным ссылкам и выводить property объектов, а также выводить конкретные поля этих объектов. Глубина запроса не ограничена, разделитель - двойное подчеркивание. *Внимание\! Django не объединяет запрос по обратной ссылке в один, поэтому он может выполняться заметно дольше для большого кол-ва объектов (например, если запросить все учетные записи у всех абонентов - будет 1 запрос для абонентов и по запросу на каждого абонента для получения его учетных записей)*
h3. Схема результата:
*Формат ответа:*
{code}
{"call": "/rest_api/v2/<model_name>/", "result": [<объект>, ...]}
{code}
тип поля result будет меняться в соответствии с данными (список для перечня объектов (objects.filter), словарь для 1 объекта (objects.get), значение метода при вызове метода и.т.д).
*Формат ошибки:*
{code}
{"call": "/rest_api/v2/<model_name>/", "error": "..."}
{code}
если в результате есть не пустое поле error, то значит запрос завершился неуспешно
*Формат объекта:*
{code}
{"pk": <id>, "model": "<model>", "fields": {"<field>": <value>, ...}
{code}
Если поле является ссылкой fk (например поле tarif у модели Abonents), то объект тарифа можно получить, задав fields=\["tarif"\], а pk тарифа, задав fields=\["tarif_id"\], например:
{code}
{"pk": <id>, "model": "Abonents", "fields": {"tarif": {"pk": <id тарифа>, "model": "Tarif", "fields": {<поля тарифа>}, "tarif_id": <id тарифа>}
{code}
Также, можно вывести только определенные поля тарифа через двойное подчеркивание: fields=\["tarif__name"\]:
{code}
{"pk": <id>, "model": "Abonents", "fields": {"tarif": {"pk": <id тарифа>, "model": "Tarif", "fields": {"name": <имя тарифа>}, "tarif_id": <id тарифа>}
{code}
Еще пример. Запрос ip адресов всех учетных записей абонента fields=\["abonent_id_users__ip"\]:
{code}
{"pk": <id>, "model": "Abonents", "fields": {"abonent_id_users": [{"pk": <id учетной записи>, "model": "Users", "fields": {"ip": "<ip>"}}, ...]}}
{code}
h3. Формирование запросов:
{code}
curl -XPOST -d 'method1=objects.all&arg1={}&fields=["tarif_id","tarif","abonent_id_users__ip","attr","child_folders_count"]' http://<ip>:8082/rest_api/v2/Abonents/ -D -
curl -XPOST -d 'method1=objects.all&arg1={}&fields=["tarif_id","tarif__name","tarif__reserve_plan","abonent_id_users__ip","attr","child_folders_count"]' http://<ip>:8082/rest_api/v2/Abonents/ -D -
{code}
h4. Для получения документации по методам
Вызовите в браузере http://<ip>:8082/rest_api/v2/ и выберите интересующую модель.
Например демо:
[http://195.64.222.86:8087/rest_api/v2/]
h3. Примеры:
Готовые примеры работы с API с помощью Python вы можете посмотреть здесь:
[github|https://github.com/carbonsoft/rest_api_example]
*Пример 1. Вывести абонентов, у которых есть учетная запись с ip = 127.1.2.3:*
{code}
curl -XPOST -d 'method1=objects.filter&arg1={"abonent_id_users__ip":"127.1.2.3"}' http://<ip>:8082/rest_api/v2/Abonents/ -D -
{code}
*или количество таких абонентов:*
{code}
curl -XPOST -d 'method1=objects.filter&arg1={"abonent_id_users__ip":"127.1.2.3"}&method2=count&arg2={}' http://<ip>:8082/rest_api/v2/Abonents/ -D -
{code}
*Пример 2. Установить абоненту с id = 45 номер квартиры 3:*
{code}
curl -XPOST 'http://<ip>:8082/rest_api/v2/Abonents/' --data 'method1=objects.get&arg1={"id":"45"}&method2=set&arg2={"a_home_number":"3"}&method3=save&arg3={}';
{code}
*Пример 3. Подключение услуги id=532 абоненту с номером договора BILL0000021*
{code}
curl -XPOST -d 'http://<ip>:8082/rest_api/v2/Abonents/' --data 'method1=objects.get&arg1={"contract_number":"BILL0000021"}&method2=add_service&arg2={"usluga_id":532}'
{code}
*Пример 4. Сколько абоненту с номером договора 1005633 нужно заплатить что проработать до 2016-10-20*
{code}
curl -XPOST -d 'method1=objects.get&arg1={"contract_number":"1005633"}&method2=get_credit_for&arg2={"end_credit_date":"2016-10-20"}' http://169.1.80.82:8082/rest_api/v2/Abonents/
{code}
*Пример 5. Выполнение отчёта 1003 с параметром phone="+79222222222"*
{code}
curl -XPOST -d 'method1=objects.get&arg1={"id":1003}&method2=get_data&arg2={"phone":"+79222222222"}' http://169.1.80.82:8082/rest_api/v2/AdminCustomReports/ -D -
{code}
*Пример 6. По абоненту с id=1383 вывести значение реквизита с id=26*
{code}
curl -XPOST -d 'method1=objects.filter&arg1={"abonent":"1383", "attribute":"26"}' http://<ip-биллинга>:8082/rest_api/v2/AttributeValues/ -D -
{code}
*Пример 7. Пример создания абонента с именем abonent, в папке 1 с тарифом с id 1*
{code}
def create_abonent(self, **kwargs):
params = {
'url': '(billing_url)/Abonents/'.format(self.api_url),
'method1': 'objects.create',
'arg1': {"name": "abonent", '"parent_id": 1,"tarif_id": 1}.
}
return self.get_api_result(self.post_request(**params))
{code}
*Пример 8. Установить абоненту с id 1321 тариф с именем Тестовый*
1. Получаем id тарифа по имени
{code}
curl -XPOST -d 'method1=objects.get&arg1={"name":"Тестовый"}' http://<ip-биллинга>:8082/rest_api/v2/tarif/ -D -
{code}
В поле pk получаем id тарифа, в данном случае 1118
2. Устанавливаем тариф абоненту по id
{code}
curl -XPOST -d 'method1=objects.get&arg1={"id":"1321"}&method2=set&arg2={"tarif_id":"1118"}&method3=save&arg3={}' http://<ip-биллинга>:8082/rest_api/v2/Abonents/ -D -
{code}
*Пример 9. Установить абоненту с номером учетной записи 1361 коммутатор с IP 1.1.1.1*
1. Получаем id коммутатора по IP
{code}
curl -XPOST -d 'method1=objects.get&arg1={"ip":"1.1.1.1"}' http://<ip-биллинга>:8082/rest_api/v2/Switch/ -D -
{code}
В поле pk получаем id коммутатора, в данном случае 1113
2. Устанавливаем коммутатор в учетную запись по id
{code}
curl -XPOST -d 'method1=objects.get&arg1={"id":"1361"}&method2=set&arg2={"switch_id":"1113"}&method3=save&arg3={}' http://<ip-биллинга>:8082/rest_api/v2/Users/ -D -
{code}
*Пример 10. Установить абоненту с номером учетной записи 1361 vlan 8*
{code}
curl -XPOST -d 'method1=objects.get&arg1={"id":"1361"}&method2=set&arg2={"router_vlan":"8"}&method3=save&arg3={}' http://<ip-биллинга>:8082/rest_api/v2/Users/ -D -
{code}
*Пример 11. Установить абоненту с номером учетной записи 1361 mac-адрес 00:AA:CC:11:44:88*
{code}
curl -XPOST -d 'method1=objects.get&arg1={"id":"1361"}&method2=set&arg2={"mac":"00:AA:CC:11:44:88"}&method3=save&arg3={}' http://<ip-биллинга>:8082/rest_api/v2/Users/ -D -
{code}
*Пример 12. Установить абоненту с номером учетной записи 1361 галочку opt82*
{code}
curl -XPOST -d 'method1=objects.get&arg1={"id":"1361"}&method2=set&arg2={"opt82":"1"}&method3=save&arg3={}' http://10.90.180.180:8082/rest_api/v2/Users/ -D -
{code}
*Пример 13. Установить абоненту с номером учетной записи 1361 порт номер 8 коммутатора 2.2.2.2*
1. Получаем id коммутатора по IP
{code}
curl -XPOST -d 'method1=objects.get&arg1={"ip":"2.2.2.2"}' http://<ip-биллинга>:8082/rest_api/v2/Switch/ -D -
{code}
В поле pk получаем id коммутатора, в данном случае 1114
2. Получаем id порта по его номеру
{code}
curl -XPOST -d 'method1=objects.get&arg1={"switch_id":"1114","num":"8"}' http://<ip-биллинга>:8082/rest_api/v2/SwitchPorts/ -D -
{code}
В поле pk получаем id порта коммутатора, в данном случае 1168
3. Устанавливаем порт в учетной записи по id порта из БД
{code}
curl -XPOST -d 'method1=objects.get&arg1={"id":"1361"}&method2=set&arg2={"switch_p":"1168"}&method3=save&arg3={}' http://<ip-биллинга>:8082/rest_api/v2/Users/ -D -
{code}