Документація API

Швидкий старт#

Мініфікувати таблицю стилів і вивести результат:

$ curl --data-urlencode 'input=.card { padding: 8px; margin: 0 auto; }' \
  https://formatter.nextwell.top/api/v1/minify/css/raw
# .card{padding:8px;margin:0 auto}

Замініть {css} на {js} або {html}, а {minify} на {beautify} — працює будь-яка комбінація.

Ендпоїнти#

Базова адреса — {base}. Усе нижче — POST, якщо не сказано інше.

{lang} — це css, js або html.

Як надіслати код#

Кожен ендпоїнт приймає тіло у трьох виглядах — обирайте той, який простіше сформувати вашому клієнту.

Форма urlencoded

Поле {input}, {type}. Такий вигляд тіла запиту усталений у подібних API мініфікації, тож готовому скрипту достатньо змінити адресу.

$ curl --data-urlencode 'input=body{margin:0;padding:0}' \
  https://formatter.nextwell.top/api/v1/beautify/css

JSON

{type} з рядком у полі {input}.

$ curl -H 'Content-Type: application/json' \
  -d '{"input":"const a=1;const b=a+1;console.log(b)"}' \
  https://formatter.nextwell.top/api/v1/beautify/js

Сире тіло

Будь-який інший content type: тілом іде сам код. Зручно для {example}.

$ curl --data-binary @style.css \
  -H 'Content-Type: text/css' \
  https://formatter.nextwell.top/api/v1/minify/css

Розмір

2 МБ на запит. Усе, що більше, повертається як 413 і навіть не читається.

Параметри запиту#

$ curl --data-urlencode 'input=.a{color:red}' \
  'https://formatter.nextwell.top/api/v1/beautify/css?indent=tab&engine=local'

Відповідь#

Успішний виклик повертає JSON:

{
  "ok": true,
  "action": "minify",
  "language": "css",
  "engine": "upstream",
  "input_bytes": 1024,
  "output_bytes": 640,
  "saved_bytes": 384,
  "saved_percent": 37.5,
  "duration_ms": 42,
  "output": "p{color:red}"
}

Відповіді звичайним текстом#

Допишіть {raw} до будь-якого ендпоїнта форматування — і тілом відповіді буде лише результат, з типом {type}. Заголовки ті самі. Зручно, коли запит іде з шелла:

$ curl -s --data-binary @app.js \
  -H 'Content-Type: text/javascript' \
  https://formatter.nextwell.top/api/v1/minify/js/raw > app.min.js

Заголовки відповіді#

$ curl -s -D - -o /dev/null --data-urlencode 'input=.a{color:red}' \
  https://formatter.nextwell.top/api/v1/minify/css

Помилки#

Будь-яка помилка — це JSON того вигляду, який усталений для подібних API: клієнт, що вже розбирає такий формат, розбере й наші помилки:

{
  "errors": [
    { "status": 429, "title": "Too many requests", "detail": "…" }
  ]
}

Ліміти запитів#

На IP-адресу, п’ять ковзних вікон, усі діють одночасно. Запит має вміститися в усі п’ять.

Коли вікно вичерпано, приходить 429 із заголовком Retry-After: у ньому секунди до відкриття найвужчого вікна. Нічого не ставиться в чергу.

Лічильники лежать у невеликій базі на диску, тож перезапуск сервісу нікому не видає нову добу.

{endpoint} показує поточний стан усіх п’яти вікон, не витрачаючи запиту.

$ curl https://formatter.nextwell.top/api/v1/limits

Зовнішній сервіс мініфікації дозволяє 30 запитів на хвилину на весь сайт, а не на кожного відвідувача. За цим стежить спільний лічильник-бакет: коли він порожній, мініфікацію CSS і JS виконує локальний рушій — замість очікування чи помилки. Під навантаженням поле engine може змінюватися, але результат в обох випадках коректний.

Який рушій виконує роботу#

Два шляхи, один контракт.

Хмара — мініфікація CSS і JS

Зовнішній сервіс мініфікації, швидкий і обережний: прибирає ті пробіли, які можна прибрати, і зберігає ті, які не можна, тож конструкції на кшталт {calc} лишаються цілими. Цей сервіс пропускає код крізь нього і нічого не додає від себе.

Локальний рушій — усе інше

Мініфікація HTML, усі три форматувальники та мініфікація CSS/JS, коли спільний ліміт зовнішнього сервісу вичерпано або сервісу задано працювати без зовнішніх викликів. Побудований на {tools}, які підвантажуються лише тоді, коли їх потребує запит, — процес у простої лишається невеликим.

Задайте {param}, щоб закріпити запит за одним шляхом.

Що зберігається#

Нічого. Код живе в пам’яті рівно стільки, скільки триває запит, і зникає. На диск він не пишеться і в логах не з’являється. У логи потрапляють лише: скорочений хеш IP, мова, дія, кількість байтів, рушій і тривалість.