Работа с API Planiqum¶

В Planiqum используется многоуровневая маршрутизация для построения путей к API. Это важно учитывать при интеграции, написании тестов и разработке новых приложений.

Swagger/OpenAPI: интерактивная документация и тестирование API¶

В Planiqum для автоматической генерации и визуализации документации по API используется Swagger (OpenAPI) через библиотеку drf-spectacular.

Swagger UI — это интерактивная страница, где можно посмотреть все доступные эндпоинты, их параметры, примеры запросов и ответов, а также протестировать API прямо из браузера.
OpenAPI schema — это формальное описание всех API в формате JSON/YAML, которое можно использовать для генерации клиентов, автотестов и интеграций.

Где найти Swagger и OpenAPI в Planiqum¶

Swagger UI:

Откройте в браузере:

http://localhost:8000/core/api/schema/swagger-ui/

Здесь вы увидите интерактивную документацию по всем API Planiqum. Для тестирования защищённых эндпоинтов потребуется авторизация (например, через cookie сессии).

OpenAPI schema (JSON):
```
http://localhost:8000/core/api/schema/
```
Можно скачать схему для генерации клиентов или анализа структуры API.

Как пользоваться¶

Откройте Swagger UI в браузере по адресу выше.
Найдите нужный эндпоинт (например, параметры, меры, корректировки и т.д.).
Посмотрите описание, параметры, примеры запросов и ответов.
Для тестирования запросов авторизуйтесь (например, через cookie сессии, если требуется).
Используйте OpenAPI schema для генерации кода клиента или автотестов (поддерживается многими инструментами).

Swagger UI — удобный способ быстро ознакомиться с возможностями API Planiqum и протестировать интеграцию без написания кода.

Формирование URL-адресов¶

В корневом urls.py проекта:

path("core/", include("planiqum.core.urls")),

В urls.py ядра:

path("hierarchy/", include("planiqum.core.hierarchy.urls")),

В urls.py приложения (например, hierarchy):

path("api/", include(router.urls)),
# router.register(r"levels", ...)

В результате, путь к endpoint для уровней будет:

/core/hierarchy/api/levels/

Аналогично формируются пути для других сущностей: - /core/hierarchy/api/items/ - /core/hierarchy/api/types/ - и т.д.

Важно: При написании тестов и интеграции с API всегда учитывайте все уровни вложенности в urls.py.

Примеры работы с API¶

Получить список уровней (Level)¶

GET /core/hierarchy/api/levels/

Получить конкретный уровень¶

GET /core/hierarchy/api/levels/{id}/

Создать новый уровень¶

POST /core/hierarchy/api/levels/
Content-Type: application/json

{
  "type": 1,
  "key": "new_level",
  "shortname": "Новый уровень"
}

Обновить уровень¶

PUT /core/hierarchy/api/levels/{id}/
Content-Type: application/json

{
  "shortname": "Новое имя"
}

Удалить уровень¶

DELETE /core/hierarchy/api/levels/{id}/

Особенности работы с полем is_hidden¶

Поле is_hidden определяет, скрыт ли уровень для обычных пользователей.
Только пользователи с разрешением view_hidden_levels видят скрытые уровни и поле is_hidden в ответе API.
Обычные пользователи не видят скрытые уровни и не получают поле is_hidden в выдаче.

Пример ответа для пользователя с разрешением¶

[
  {
    "id": 1,
    "shortname": "Видимый уровень",
    "is_hidden": false
  },
  {
    "id": 2,
    "shortname": "Скрытый уровень",
    "is_hidden": true
  }
]

Пример ответа для обычного пользователя¶

[
  {
    "id": 1,
    "shortname": "Видимый уровень"
  }
]

Советы¶

Если endpoint не найден (404), проверьте структуру urls.py на всех уровнях.
Для DRF ViewSet-ов используйте router и обращайтесь по соответствующим путям.
Для тестирования используйте корректные пути, учитывая все уровни вложенности.

Как подключаться к API Planiqum через curl с авторизацией (CSRF)¶

Для большинства API Planiqum требуется авторизация пользователя. Если используется стандартная Django-форма логина, для запросов через curl нужно корректно обработать CSRF-токен и cookie сессии.

Пошаговая инструкция:¶

Получить CSRF-cookie и сессионные cookie:

curl -c cookies.txt -s http://localhost:8000/accounts/login/ > /dev/null

Извлечь CSRF-токен из cookie:

export CSRFTOKEN=$(grep csrftoken cookies.txt | awk '{print $7}')

Выполнить POST-запрос на логин с передачей CSRF-токена:

curl -b cookies.txt -c cookies.txt -X POST \
  -d "username=ВАШ_ЛОГИН" \
  -d "password=ВАШ_ПАРОЛЬ" \
  -d "csrfmiddlewaretoken=$CSRFTOKEN" \
  -H "Referer: http://localhost:8000/accounts/login/" \
  http://localhost:8000/accounts/login/

После этого используйте cookies.txt для авторизованных запросов к API:
```
curl -b cookies.txt http://localhost:8000/core/parameters/api/parameters/
```

Если используется другой путь логина или токен-авторизация, см. соответствующую документацию по вашему способу аутентификации.

Получение параметров через API: кратко и подробно¶

В Planiqum реализовано два способа получения информации о параметрах через API:

1. Краткий список параметров¶

Эндпоинт:
```
GET /core/parameters/api/parameters/
```
Описание: Возвращает только основные поля параметра (id, app_name, name, label, описание, backup-флаги и т.д.).

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

[
  {
    "id": 1,
    "app_name": "demand",
    "name": "План продаж",
    "label": "demand - План продаж",
    "description": null,
    "is_backup": false,
    "has_backup": true,
    "revision_type": 0
  }
]

2. Полная структура параметров (с измерениями и мерами)¶

Эндпоинт:

GET /core/parameters/api/parameters/full/

Описание: Возвращает все поля параметра, а также массивы dimensions и measures с полной структурой.

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

[
  {
    "id": 1,
    "app_name": "demand",
    "name": "План продаж",
    "label": "demand - План продаж",
    "description": null,
    "is_backup": false,
    "has_backup": true,
    "revision_type": 0,
    "dimensions": [
      {
        "id": 1,
        "key": "dpu",
        "name": "Объект планирования спроса"
        // ...
      }
    ],
    "measures": [
      {
        "id": 1,
        "key": "demand_plan__qty",
        "name": "Кол-во"
        // ...
      }
    ]
  }
]

3. Примечания¶

Обычный запрос /core/parameters/api/parameters/ — только базовая информация.
Запрос /core/parameters/api/parameters/full/ — вся структура параметра, включая измерения и меры.
Для получения только измерений или мер используйте отдельные эндпоинты:
GET /core/parameters/api/dimensions/
GET /core/parameters/api/measures/

Подробнее о структуре параметров, измерений и мер см. разделы выше и dev/basic_concepts.md.