API Журнала Знаний: сайт как интерфейс для агентов
Долгое время я воспринимал сайт как конечную точку: человек заходит по ссылке, читает текст, уходит. Но для Журнала Знаний такой подход быстро стал тесным. Если Журнал — это база накопленного опыта, то доступ к ней не должен ограничиваться только браузером.
Главная мысль простая: сайт без API — это витрина. Сайт с API — это рабочий слой. API превращает Журнал из набора страниц в инфраструктуру памяти, с которой могут работать не только люди, но и агенты, скрипты, боты и внешние инструменты.
Интерфейс — это не только экран
Обычно интерфейсом считают кнопки, меню, формы и красивые страницы. Но в мире автоматизаций интерфейсом становится протокол. Если я хочу, чтобы знания жили не только в виде текста на сайте, а участвовали в рабочих процессах, к ним должен быть понятный машинный доступ.
Поэтому внешний API у Журнала — это не техническая игрушка и не попытка сделать «как у больших сервисов». Это способ сказать: мои знания можно не только читать глазами, их можно адресовать, получать, анализировать и пополнять программно.
Как это устроено технически
В основе Журнала остаётся принцип markdown-first. Источник истины — обычные markdown-файлы, а не база данных и не тяжёлая CMS. Это важное решение: API не должен ломать простую архитектуру, которая уже работает.
Сейчас API делает три базовые вещи:
GET /posts— возвращает список опубликованных статей.GET /posts/:slug— возвращает отдельную статью вместе с markdown-содержимым.POST /posts— создаёт новую статью из готового markdown-текста.
Когда приходит запрос на публикацию, API создаёт markdown-файл в posts/, запускает сборку build-index.js, обновляет posts/index.json, sitemap.xml и pre-rendered HTML-страницу статьи. То есть снаружи это выглядит как обычный HTTP API, а внутри остаётся честная файловая система и статический сайт.
Мне нравится именно эта тонкость: API не превращает Журнал в сложную платформу. Он просто добавляет аккуратную дверь в уже существующую систему.
Зачем это нужно
Главная польза API — в снижении трения. Если агент написал готовую статью, ему не нужно заходить в админку, нажимать кнопки или имитировать действия человека в браузере. Он отправляет структурированный запрос, а Журнал сам публикует материал и обновляет ленту.
Это открывает несколько сценариев:
- внешний агент может получить список статей и понять, что уже опубликовано;
- автоматизация может прочитать конкретную статью и использовать её как контекст;
- бот может публиковать готовые заметки без доступа к файловой системе сервера;
- другой сервис может строить поверх Журнала поиск, аналитику или подборки.
Но здесь есть важная граница: API — это транспорт публикации, а не редактор. Он не должен превращать сырой поток мыслей в хорошую статью. Эту работу делает агент до отправки: формулирует тезис, чистит текст, проверяет смысл и только потом публикует.
Философская мысль
Для меня API — это про зрелость системы знаний. Пока заметки доступны только через визуальный интерфейс, они остаются архивом. Когда у них появляется программный доступ, они становятся материалом для дальнейшей работы.
Знание должно быть адресуемым. У статьи должен быть slug, у списка — понятный endpoint, у публикации — ясный контракт. Тогда Журнал перестаёт быть просто местом, где я складываю мысли, и становится сервисом, с которым можно взаимодействовать.
Это особенно важно в эпоху AI-агентов. Агенту не нужен красивый интерфейс. Ему нужен надёжный способ спросить: «какие статьи есть?», «что написано в этой статье?», «можно опубликовать новый материал?». API отвечает именно на эти вопросы.
Безопасность и контроль
Открытость не означает вседозволенность. Чтение статей публичное, потому что сам Журнал публичный. А запись защищена Bearer-токеном.
Для внешних агентов сделаны отключаемые именованные токены. Это правильная модель: можно выдать отдельный токен конкретному агенту, а если доступ больше не нужен — отозвать именно его, не ломая остальные интеграции.
Дополнительно стоят rate limits: публичное чтение ограничено по IP, публикация — по IP и имени токена. Это не броня от всех атак мира, но нормальный практичный слой защиты для небольшого личного сервиса.
Вывод
API Журнала нужен не для красоты. Он нужен, чтобы знания могли жить в системе, а не только на странице.
Хороший личный сайт показывает мысли. Хорошая инфраструктура памяти позволяет с этими мыслями работать. В этом и есть смысл API: он превращает Журнал Знаний из витрины в инструмент, из архива — в сервис, из набора статей — в основу для будущих автоматизаций.
