REST API
Базовый URL: https://<your-veresk-host>/api/v1. Аутентификация — API-токеном.
Полный актуальный справочник со схемами запросов и ответов отдаёт ваш экземпляр Veresk по адресу /api/v1/docs (Swagger). Эта страница объясняет, как части складываются вместе.
Эндпоинты
| Область | Что можно делать |
|---|---|
| Аккаунт | GET /me |
| Проекты | Список доступных проектов; получить один |
| Версии | Список, создание от родителя, изменение описания, публикация, сравнение двух версий, копирование файлов между версиями |
| Файлы | Список (с фильтрами search и tag), создание, метаданные, переименование и описание, чтение и запись содержимого по версиям, сброс к унаследованному содержимому |
| Потребители и теги | Список потребителей; список и создание тегов; назначение файла потребителям и тегам |
Типичный сценарий: поменять значение и опубликовать
GET /projects— найти id проекта.GET /projects/{projectId}/files?search=settings— найти id файла.GET /projects/{projectId}/files/{fileId}/versions/{versionId}— прочитать содержимое. Сохраните полученныйetag.PUTна тот же URL с полным новым содержимым иetag.POST /projects/{projectId}/versions/{versionId}/publish.
Безопасное обновление через etag
Запись файла заменяет его всё содержимое в этой версии, и у версии появляется собственная копия файла. Передайте etag, полученный при чтении. Если за это время кто-то изменил файл, запрос завершится ошибкой конфликта, а не перезапишет чужое изменение.
JSON-файлы принимают JSON-значение, остальные — строку. Заблокированная версия отклоняет запись.
Наследование в API
Чтение содержимого файла возвращает содержимое в том виде, как оно отдаётся в этой версии: собственная копия или унаследованная. Ответ сообщает, из какой версии оно реально взято (resolvedVersion).
След автоматизации
Файлы, созданные или изменённые через API, получают теги api-created и api-edited, поэтому видно, что трогала автоматизация.
Недоступно через API
В целях безопасности публичный API не может удалять и создавать проекты, менять роли, перевыпускать ключ шифрования, менять Git, флаги шифрования и настройки валидации. Для этого используйте интерфейс.