Публикация постов через API dev.to без дублей
Автор: Евгений Падежнов
Один POST-запрос публикует статью на dev.to. Проблемы начинаются со второго.
Разработчики, которые дублируют посты из личного блога, часто пишут скрипт на скорую руку, запускают его дважды и получают две одинаковые статьи. Другие теряют поисковый трафик, потому что копия на dev.to обходит оригинал в выдаче. А кто-то слишком поздно узнаёт, что в API нет эндпоинта для загрузки изображений.
В этом руководстве разобран весь цикл публикации. Сначала получаем ключ, затем создаём черновики, обновляем статью вместо создания дубля, задаём канонический URL и запускаем всё из CI. API входит в Forem — open-source платформу, на которой работает dev.to. Документация лежит на developers.forem.com.
Зачем вообще автоматизировать публикацию на dev.to
Ручной кросспостинг — это скопировать, вставить, поправить форматирование, заново проставить теги и указать каноническую ссылку. На один пост уходит всего несколько минут. Но команды, которые публикуются каждую неделю, повторяют это достаточно часто, чтобы начать ошибаться.
Согласно руководству Sourcegraph по автоматизации рутинных задач, первый шаг — определить повторяющуюся задачу. Второй — подобрать подходящий инструмент. Кросспостинг проходит обе проверки. Задача каждый раз одна и та же, а API dev.to небольшой и стабильный.
В разборе инструментов автоматизации блога на YouTube работа над постом делится на шесть этапов: идея, исследование, черновик, оптимизация, публикация и распространение. По словам автора видео, большинство инструментов затрагивают только написание черновика. Публикация и распространение остаются ручными. Короткий скрипт для API dev.to закрывает именно этот пробел.
Проще говоря: оригинал остаётся на сайте, которым владеет автор, а на dev.to уходит синхронизированная копия. Скрипт следит, чтобы они не расходились.
Шаг 1: получите API-ключ и надёжно его храните
Ключ создаётся в настройках аккаунта dev.to. Откройте Settings, затем Extensions и найдите раздел «DEV Community API Keys». Дайте ключу имя и сгенерируйте его.
Ключ даёт право записи в аккаунт. Обращайтесь с ним как с паролем.
- Храните его в переменной окружения, например
DEVTO_API_KEY. - Не держите его в репозитории. Добавьте
.envв.gitignore. - В CI используйте хранилище секретов платформы, а не обычную переменную.
- Если ключ когда-нибудь попал в лог или коммит, отзовите его и создайте новый.
Частая ошибка: выводить при отладке заголовки запроса целиком. Ключ передаётся в заголовке api-key, так что подробный лог его раскрывает.
Быстрая проверка, что ключ работает:
curl -s https://dev.to/api/articles/me/all \
-H "api-key: $DEVTO_API_KEY" \
-H "Accept: application/vnd.forem.api-v1+json" | head -c 300
Если пришёл JSON-массив, ключ действителен. Ответ 401 означает, что ключ неверный или отозван.
Заголовок Accept выбирает версию 1 API Forem. В старых примерах из интернета его нет. Явная передача защищает скрипт от незаметных изменений в поведении API.
Шаг 2: создайте статью как черновик
Эндпоинт — POST https://dev.to/api/articles. Все поля в теле запроса оборачиваются в объект article.
curl -s -X POST https://dev.to/api/articles \
-H "api-key: $DEVTO_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.forem.api-v1+json" \
-d '{
"article": {
"title": "Publishing via the dev.to API",
"body_markdown": "## Intro\n\nArticle text in Markdown.",
"published": false,
"tags": ["devto", "api", "automation"],
"canonical_url": "https://example.com/blog/devto-api/",
"description": "Short summary for previews."
}
}'
В ответе приходят id и url новой статьи. Сохраните id. От него зависят все последующие обновления.
Самые важные поля:
| Поле | Назначение |
|---|---|
title |
Заголовок статьи |
body_markdown |
Полный текст в Markdown |
published |
false создаёт черновик, true сразу публикует |
tags |
До четырёх тегов, в нижнем регистре, без пробелов |
canonical_url |
Ссылка на оригинальный пост |
main_image |
URL обложки |
series |
Объединяет связанные посты в серию |
description |
Текст превью в лентах и карточках ссылок |
Главное: начинайте с "published": false. Черновик можно проверить в редакторе dev.to. Опубликованный пост сразу появляется в лентах, и последующее удаление не отменит уведомления, уже ушедшие подписчикам.
Front matter внутри body_markdown
dev.to также принимает front matter в стиле Jekyll в начале body_markdown:
---
title: Publishing via the dev.to API
published: false
tags: devto, api, automation
canonical_url: https://example.com/blog/devto-api/
cover_image: https://example.com/img/cover.png
---
## Intro
Это удобно, если в исходных файлах front matter уже есть. Но смешивание двух способов порождает путаницу. Если поле указано во front matter, а в JSON у него другое значение, непонятно, какое из них победит.
Выберите один источник истины. В скриптах полями JSON управлять проще. Перед отправкой удаляйте front matter исходного блога: его ключи редко совпадают с названиями полей dev.to.
Шаг 3: обновляйте, а не создавайте заново
Проблема дублей возникает при повторном запуске скрипта. Каждый POST создаёт новую статью. dev.to не отсеивает дубли ни по заголовку, ни по каноническому URL.
Решение — хранить соответствие между локальным постом и id на dev.to. Тогда скрипт выбирает между созданием и обновлением.
idне сохранён: отправитьPOST /api/articles.idсохранён: отправитьPUT /api/articles/{id}с телом того же вида.
Где хранить соответствие, зависит от устройства проекта:
- Добавить поле
devto_idво front matter поста и закоммитить его обратно. - Держать в репозитории небольшой JSON-файл, например
devto-map.json. - При каждом запуске искать статью через
GET /api/articles/me/allи сверять поcanonical_url.
Вариант 3 не требует хранить состояние. Зато он стоит лишнего запроса, а список отдаётся постранично (параметры page и per_page). Вариант 1 самый прозрачный: связь видна прямо в файле.
Вот скрипт на Node.js без зависимостей (Node 18 или новее, встроенный fetch). Он использует вариант 3, поэтому его безопасно запускать повторно.
// publish-devto.mjs
const API = "https://dev.to/api";
const headers = {
"api-key": process.env.DEVTO_API_KEY,
"Content-Type": "application/json",
"Accept": "application/vnd.forem.api-v1+json",
};
async function findByCanonical(canonical) {
for (let page = 1; page <= 20; page++) {
const res = await fetch(`${API}/articles/me/all?page=${page}&per_page=100`, { headers });
if (!res.ok) throw new Error(`List failed: ${res.status}`);
const items = await res.json();
if (items.length === 0) return null;
const hit = items.find((a) => a.canonical_url === canonical);
if (hit) return hit;
}
return null;
}
export async function upsert(article) {
const existing = await findByCanonical(article.canonical_url);
const url = existing ? `${API}/articles/${existing.id}` : `${API}/articles`;
const method = existing ? "PUT" : "POST";
const res = await fetch(url, { method, headers, body: JSON.stringify({ article }) });
if (res.status === 429) throw new Error("Rate limited: retry later");
if (!res.ok) throw new Error(`${method} failed: ${res.status} ${await res.text()}`);
const data = await res.json();
console.log(`${method} ok: id=${data.id} ${data.url}`);
return data;
}
В скрипте нет внешних пакетов, поэтому поверхность атаки остаётся маленькой. Скрипту публикации, у которого есть ключ с правом записи, дерево зависимостей ни к чему.
Попробуйте: запустите скрипт дважды с одним и тем же canonical_url. Первый запуск должен вывести POST ok, второй — PUT ok. В панели должна появиться только одна статья.
Обработка ошибок и лимитов запросов
API возвращает стандартные HTTP-коды. На практике чаще всего встречаются:
401: ключ отсутствует или недействителен.422: ошибка валидации. Типичные причины — слишком много тегов, тег с пробелами или пустой заголовок.429: слишком много запросов. Подождите и повторите с нарастающей задержкой.
Не повторяйте 422 автоматически. Запрос каждый раз будет падать одинаково. Выведите тело ответа. Обычно в нём указано проблемное поле.
Шаг 4: канонический URL и изображения
canonical_url защищает оригинал
Когда один и тот же текст есть на двух доменах, поисковики выбирают одну версию основной. Без подсказки крупная платформа вроде dev.to может победить личный блог.
Поле canonical_url добавляет на страницу dev.to тег <link rel="canonical">. Он указывает поисковикам на оригинал. Копия на dev.to при этом всё равно получает читателей из собственной ленты платформы.
Частая ошибка: указывать каноническим URL страницу, которая делает редирект или возвращает 404. Сначала опубликуйте оригинал, убедитесь, что он открывается, и только потом делайте кросспост.
Изображения нужно хранить в другом месте
В публичном API нет эндпоинта для загрузки. main_image и картинки внутри body_markdown должны быть абсолютными URL, которые уже работают.
Практические правила:
- Храните изображения в оригинальном блоге или на CDN.
- Перед отправкой заменяйте относительные пути вроде
./img/chart.pngна полныеhttps://-адреса. - Проверяйте, что каждый URL возвращает
200и тип содержимого изображения.
dev.to скачивает и кэширует изображения у себя. Если в момент публикации URL не работает, в посте может остаться битая картинка. Предварительная проверка в скрипте ловит это почти даром.
Шаг 5: запуск из CI
Естественный триггер — пуш в основную ветку блога. Задача GitHub Actions может запускать скрипт для новых или изменённых постов.
name: Cross-post to dev.to
on:
push:
branches: [main]
paths: ["content/blog/**"]
jobs:
publish:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@<full-commit-sha>
- uses: actions/setup-node@<full-commit-sha>
with:
node-version: "20"
- run: node scripts/crosspost.mjs
env:
DEVTO_API_KEY: ${{ secrets.DEVTO_API_KEY }}
Закрепляйте actions по полному SHA коммита, а не по тегу. Тег позже можно перевесить на другой код. SHA — нельзя.
Согласно обзору инструментов автоматизации от Zenhub, Jenkins — давно известный open-source сервер автоматизации для конвейеров сборки и деплоя. Он подойдёт для той же задачи командам, у которых он уже работает. Для визуальных сценариев подборка Collect описывает n8n — инструмент на узлах, где каждый сервис или действие является соединяемым узлом. Узел HTTP-запроса может вызвать API dev.to без написания скрипта.
Для одного блога обычно хватает скрипта на 40 строк в существующем CI. Отдельная платформа автоматизации — это ещё одна система, которую придётся поддерживать.
Тем, кто собирает это вместе с ИИ-агентом для программирования, пригодится руководство по установке Claude Code — там описана настройка. В обзоре стека ИИ-IDE редакторы сравниваются на подобных задачах. В любом случае проверяйте сгенерированный код, прежде чем давать ему ключ с правом записи.
Что не сработало
Несколько подходов выглядели нормально, но подвели на практике:
- Публикация сразу с
published: trueиз CI. Одна ошибка форматирования ушла подписчикам раньше, чем кто-то её заметил. Сначала черновики, потом ручное или плановое переключение. - Поиск существующих статей по заголовку. Заголовки меняются при редактировании. Сопоставление сломалось и создало дубль.
canonical_urlили сохранённыйidстабильны. - Отправка исходного Markdown без изменений. Шорткоды конкретного сайта и относительные пути к картинкам отобразились сырым текстом. Небольшой шаг преобразования обязателен.
Часто задаваемые вопросы
Как быть с изображениями при публикации через API dev.to?
API не принимает загрузку файлов. Храните изображения на оригинальном сайте или CDN и используйте в body_markdown абсолютные https://-адреса. Относительные пути заменяйте в скрипте перед отправкой.
Как задать обложку поста через API dev.to?
Передайте публичный URL изображения в поле main_image объекта article. Если вместо этого используется front matter, аналогичный ключ — cover_image. Перед публикацией проверьте, что URL возвращает 200.
Стоит ли сначала создавать посты как черновики?
Да. Создайте пост с published: false, проверьте отрисованный черновик на dev.to, затем отправьте PUT с published: true. Хороший сигнал к публикации — чистое превью с работающими картинками и каноническим URL, который открывается.
Как использовать canonical_url при кросспостинге?
Укажите в canonical_url рабочий адрес оригинального поста. Тогда dev.to отметит оригинал как основную версию для поисковиков. Публикуйте оригинал первым, чтобы ссылка никогда не вела на несуществующую страницу.
Как запланировать публикацию на определённое время?
В документированном API нет надёжного поля для отложенной публикации, поэтому планирование делается вне dev.to. Создайте пост как черновик, затем запустите задачу по расписанию (cron или workflow GitHub Actions по расписанию), которая выставит published: true в нужное время.
Что попробовать прямо сейчас
Сгенерируйте API-ключ, экспортируйте его как DEVTO_API_KEY и выполните команду curl из шага 2 с "published": false. Откройте черновик в панели dev.to. Если он отображается правильно и канонический URL указан, базовый конвейер работает. Всё остальное в этом руководстве строится на этом единственном запросе.
Информация актуальна на момент публикации. Условия, цены и правила могут измениться — уточняйте у профильных специалистов.