Понятный интерфейс.
Открытая механика.
Начните с рабочего пространства или проверьте API.
Примеры соответствуют публичной версии 0.1.
01 / Начало работы
Откройте тестовое пространство, ознакомьтесь с условиями и нажмите «Создать пространство». Загрузите учебный файл, откройте «Заметки» и посмотрите «Историю».
Сессия доступна только в браузере, где была создана. Режим инкогнито создаёт отдельное пространство. После 24 часов потребуется начать заново.
02 / Сессия и доступ
API использует cookie istovia_session. Для запросов изменения добавьте X-Istovia-Client: web. Межсайтовые запросы изменения запрещены. Отдельных пользовательских API-ключей пока нет.
curl -c cookies.txt -X POST \ -H 'X-Istovia-Client: web' \ https://istovia.io/api/v1/session curl -b cookies.txt \ https://istovia.io/api/v1/workspace
Файл cookies.txt содержит доступ к вашему демо. Не публикуйте его и удалите после проверки.
03 / Методы
| Метод | Путь | Назначение |
|---|---|---|
| GET | /api/v1/health | Проверка приложения и БД |
| GET / POST | /api/v1/session | Проверить / создать демо |
| GET | /api/v1/workspace | Файлы, заметки, лимиты |
| POST | /api/v1/files | Загрузить файл |
| GET / DELETE | /api/v1/files/{id} | Скачать / удалить файл |
| POST | /api/v1/notes | Создать заметку |
| PATCH / DELETE | /api/v1/notes/{id} | Изменить / удалить заметку |
| GET | /api/v1/events | Последние 100 событий |
| DELETE | /api/v1/workspace | Удалить пространство |
04 / Загрузка файла
Тело запроса содержит байты файла. Имя передаётся в X-File-Name с URL-кодированием. Используется обычный POST; скачивание — GET. Содержимое файла не передаётся в заголовках.
curl -b cookies.txt -X POST \ -H 'X-Istovia-Client: web' \ -H 'X-File-Name: brief.txt' \ -H 'Content-Type: application/octet-stream' \ --data-binary @brief.txt \ https://istovia.io/api/v1/files
Загруженный файл доступен только в своей сессии. Ответ скачивания имеет Content-Disposition: attachment.
Создание заметки
curl -b cookies.txt -X POST \
-H 'X-Istovia-Client: web' \
-H 'Content-Type: application/json' \
-d '{"title":"План","body":"Собрать материалы"}' \
https://istovia.io/api/v1/notesОбращения
POST /api/v1/feedback возвращает номер, личный токен и ссылку. Для статуса используйте GET /api/v1/feedback/{reference} с Authorization: Bearer TOKEN. Ссылка и токен действуют 30 дней; не передавайте их третьим лицам. Статусы: new, in_progress, answered, closed. Ответ оператора доступен в поле reply.
05 / Лимиты и ошибки
5 МБ на файл, 25 МБ на ZIP для импорта, 20 МБ на пространство, 30 файлов, 30 заметок и 24 часа доступа. Частота изменений ограничена. При превышении сервис вернёт понятную ошибку JSON.
400— некорректные данные.401— сессия отсутствует или истекла.403— запрещённый источник или отсутствует служебный заголовок.404— объект не найден в вашем пространстве.413— превышен размер или лимит объектов.429— слишком частые запросы.
06 / Статические материалы
Публичные изображения, логотип и стили сайта находятся в /assets/v1/. Версия в пути позволяет обновлять материалы без смешивания старого и нового оформления.
Приватные API и пользовательские файлы возвращают Cache-Control: private, no-store. Не кэшируйте их на CDN. Готовые наборы доступны в библиотеке. При создании сессии можно передать {"template":"handoff"}; другие варианты — blank, design, publication. Существующее пространство сохраняется. API также доступен по адресу https://api.istovia.io/api/v1/, публичные материалы — на assets.istovia.io, состояние сервисов — на status.istovia.io. Сессии каждого домена независимы.
Передача материалов
Владелец создаёт ссылку через POST /api/v1/shares с полями seconds (3600, 21600 или 86400) и comments (boolean). Ответ содержит URL с токеном после #. Активные ссылки: GET /api/v1/shares; отзыв: DELETE /api/v1/shares/{id}.
Гостевые запросы используют Authorization: Bearer TOKEN: GET /api/v1/shared, GET /api/v1/shared/files/{id}, GET /api/v1/shared/export. Токен не нужно передавать в URL запроса. Комментарии: GET/POST /api/v1/shared/files/{id}/comments; POST доступен только по ссылке с разрешением и требует author и body.
Владелец загружает новые версии бинарным POST на /api/v1/files/{id}/versions. GET по этому адресу возвращает историю, скачивание версии: /api/v1/files/{id}/versions/{versionId}. Комментарии владельца: GET/POST /api/v1/files/{id}/comments; отметка решения: PATCH /api/v1/files/{id}/comments/{commentId} с boolean-полем resolved.
Полный экспорт владельца: GET /api/v1/workspace/export. ZIP содержит текущие файлы, версии, заметки и manifest.json с комментариями. Общие ссылки не открывают историю версий. Срок жизни пространства — 24 часа, общий лимит с версиями — 20 МБ. Все операции записи требуют X-Istovia-Client: web.
Организация и восстановление
Переименование пространства: PATCH /api/v1/workspace с {"title":"Название"}. Материал: PATCH /api/v1/files/{id} с name и/или status: draft, review, ready. Изменение имени не создаёт новую версию.
При загрузке файла можно указать URL-кодированный относительный путь папки в X-File-Folder и постоянный идентификатор попытки X-Upload-ID (32 строчных шестнадцатеричных символа). Повтор той же загрузки с тем же содержимым возвращает уже созданный файл, конфликт — 409. Список файлов содержит folder, status и число нерешённых комментариев unresolved.
Восстановление: бинарный POST /api/v1/workspace/import с ZIP-экспортом ISTOVIA. Ответ 201 содержит число добавленных files и notes. Архив до 25 МБ, распакованные файлы с версиями должны помещаться в лимит пространства 20 МБ. Все материалы добавляются одной операцией: при ошибке или нехватке места ничего не добавляется. Существующие файлы сохраняются. Комментарии из архива помечены imported: 1; их авторство не подтверждается. Ссылки доступа не восстанавливаются.
При недоступности хранилища ответ 503 предлагает повторить операцию позднее. Демо не заменяет резервную копию: скачивайте архив до окончания 24 часов.