Публичное API htaccess.ru — план (черновик)

Идея

Все веб-инструменты htaccess.ru работают через браузер: вставил .htaccess — получил результат. Но для автоматизации — CI/CD, деплой-скрипты, IDE-плагины, pre-commit хуки — нужен программный доступ.

Идея публичного API: дать те же движки через HTTP:

• Линтер (/check/) — проверка синтаксиса и устаревших директив.
• Объяснялка (/explain/) — построчное объяснение файла.
• Аудит (/audit/) — находки по безопасности, производительности, совместимости.
• Генератор (/generator/) — сборка .htaccess из чекбоксов/параметров.
• Конвертеры (/apache24/, /nginx/) — перевод в Apache 2.4 Require-синтаксис и nginx-конфиг.
• Тестер mod_rewrite (/rewrite/) — проверка RewriteRule на конкретном URL.
• Проверка совместимости (/compat/) — минимальная версия Apache, нужные модули.

База и соглашения

• Базовый URL: https://htaccess.ru/api/v1/ (версия в пути — при несовместимых изменениях выходит /v2/).
• Только HTTPS — HTTP-запросы будут перенаправляться или отклоняться.
• Content-Type: application/json — и в запросе, и в ответе.
• Stateless — сервер не хранит состояние между запросами; каждый запрос самодостаточен.
• CORS — включён для GET-эндпоинтов (справочник директив и т.п.); для POST — по запросу или с токеном.

Аутентификация

• Без ключа (анонимно): базовый лимит по IP, достаточный для разовых проверок.
• С токеном: заголовок Authorization: Bearer <token> — токен из личного кабинета (которого тоже пока нет). Даёт повышенные лимиты.
• Не передавайте токен в URL — только в заголовке.

Предполагаемые эндпоинты

Список проектируемых эндпоинтов:

• POST /api/v1/lint — линтер: принимает {"htaccess":"..."}, возвращает находки с уровнями severity/line/title/detail/fix и флаг fatal.
• POST /api/v1/explain — объяснялка: построчное объяснение с полями raw/summary/detail/depth, группировка по блокам.
• POST /api/v1/audit — аудит: находки + рекомендации + список хорошего (что уже правильно).
• POST /api/v1/convert/apache24 — конвертер Apache 2.2 → 2.4: принимает .htaccess, возвращает переведённый файл и список замечаний.
• POST /api/v1/convert/nginx — конвертер в nginx-конфиг: аналогично, с пометками «проверить вручную».
• POST /api/v1/rewrite-test — тестер mod_rewrite: принимает .htaccess, URL, хост, флаг HTTPS; возвращает пошаговую трассировку и результат (rewrite / redirect / forbidden / unchanged).
• POST /api/v1/generate — генератор: принимает набор блоков ({"https":true,"gzip":true,...}) и параметры; возвращает готовый .htaccess.
• POST /api/v1/compat — проверка совместимости: минимальная версия Apache, нужные модули, требуемые AllowOverride-группы, устаревшие директивы.
• GET /api/v1/directives — справочник директив в JSON (без тела, кэшируется).

Форматы запроса и ответа для двух ключевых эндпоинтов:

{
  "htaccess": "RewriteEngine On\nRewriteRule ^old$ /new [R=301,L]"
}

{
  "ok": true,
  "fatal": false,
  "findings": [
    {
      "severity": "info",
      "line": 2,
      "title": "Редирект без HTTPS-канонизации",
      "detail": "RewriteRule с [R=301] работает, но без RewriteCond по HTTPS может создать петлю на SSL-прокси.",
      "fix": "Добавьте RewriteCond %{HTTPS} on перед правилом редиректа."
    }
  ]
}

// Запрос:
{
  "htaccess": "RewriteEngine On\nRewriteRule ^old$ /new [R=301,L]",
  "url": "/old",
  "host": "example.com",
  "https": true
}

// Ответ:
{
  "result": "redirect",
  "target": "/new",
  "status": 301,
  "steps": [
    {
      "rule": "RewriteRule ^old$ /new [R=301,L]",
      "matched": true,
      "action": "redirect 301 /new"
    }
  ]
}

Пример запроса

Как это выглядело бы из командной строки:

curl -s https://htaccess.ru/api/v1/lint \
  -H 'Content-Type: application/json' \
  -d '{"htaccess":"RewriteRule ^old$ /new [R=301,L]"}'

{
  "ok": true,
  "fatal": false,
  "findings": []
}

Мини-пример на JavaScript (fetch):

const res = await fetch('https://htaccess.ru/api/v1/lint', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ htaccess: 'Options -Indexes\n' }),
});
const data = await res.json();
console.log(data.findings); // массив находок

Ошибки и лимиты

Проектируемые HTTP-коды:

• 200 OK — запрос обработан; даже если в .htaccess есть проблемы, код 200 — сами проблемы в теле ответа.
• 400 Bad Request — невалидный JSON или отсутствует обязательное поле htaccess.
• 413 Content Too Large — ввод превышает лимит (~64 КБ).
• 422 Unprocessable Entity — ввод не похож на .htaccess (например, передан HTML или бинарные данные).
• 429 Too Many Requests — превышен лимит; заголовки X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After укажут, когда повторить.
• 5xx — ошибка на нашей стороне; тело ответа содержит {"error":"..."}.

Предварительные лимиты без ключа: ~60 запросов в час на IP. Числа предварительные — при наличии ключа лимиты выше. При превышении дождитесь срока из Retry-After или используйте токен.

Приватность

• Переданный .htaccess обрабатывается и не сохраняется (план — не логировать тело запроса, только метаданные для rate-limiting).
• Не передавайте секреты: пароли в .htpasswd-путях, ключи API в комментариях. В самом .htaccess они обычно не хранятся, но всё же.
• Это публичный сервис: для абсолютной приватности используйте локальные инструменты: apachectl -t (синтаксическая проверка), httpd -t.

Обратная связь

Если такое API было бы полезно для вашего проекта — расскажите:

• Какие эндпоинты нужны в первую очередь?
• Какие форматы запроса и ответа удобны (curl / fetch / Python / GitHub Actions)?
• Какие лимиты приемлемы для вашего use-case?

Пока API нет — используйте веб-инструменты htaccess.ru напрямую через браузер.

Ссылки

• Все инструменты htaccess.ru.
• Линтер .htaccess — проверка синтаксиса.
• Объяснялка .htaccess — построчное объяснение.
• Аудит .htaccess — безопасность, производительность.
• Конвертер Apache 2.2 → 2.4.
• Конвертер .htaccess → nginx.
• Тестер RewriteRule.
• Проверка совместимости .htaccess.
• Генератор .htaccess.
• Справочник директив .htaccess.