Dokumentacja API

Szybki start#

Zminifikuj arkusz stylów i wypisz wynik:

$ 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}

Zamień {css} na {js} albo {html}, a {minify} na {beautify} — działa każda kombinacja.

Endpointy#

Adres bazowy to {base}. Wszystko poniżej to POST, o ile nie napisano inaczej.

{lang} to css, js albo html.

Wysyłanie kodu#

Każdy endpoint przyjmuje treść w trzech postaciach — wybierz tę, którą łatwiej złożyć twojemu klientowi.

Formularz urlencoded

Pole {input}, {type}. Taką postać przyjmują zwyczajowo API minifikacji, więc istniejący skrypt zmienia tylko adres.

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

JSON

{type} z łańcuchem znaków w polu {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

Surowa treść

Dowolny inny content type: treścią jest sam kod. Wygodne przy {example}.

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

Rozmiar

2 MB na żądanie. Wszystko większe wraca jako 413 i nie jest nawet czytane.

Parametry zapytania#

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

Odpowiedź#

Udane wywołanie zwraca 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}"
}

Odpowiedzi zwykłym tekstem#

Dopisz {raw} do dowolnego endpointu formatowania, a treścią odpowiedzi będzie wyłącznie wynik, jako {type}. Nagłówki są te same. Przydatne, gdy wywołanie idzie z powłoki:

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

Nagłówki odpowiedzi#

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

Błędy#

Każdy błąd to JSON w postaci przyjętej dla tego rodzaju API, więc klient, który obsługuje już taką postać, obsłuży i nasze błędy:

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

Limity żądań#

Na adres IP, pięć okien przesuwnych, wszystkie egzekwowane naraz. Żądanie musi zmieścić się we wszystkich pięciu.

Gdy okno jest wyczerpane, wraca 429 z nagłówkiem Retry-After podającym sekundy do otwarcia najciaśniejszego z nich. Nic nie jest kolejkowane.

Liczniki leżą w małej bazie na dysku, więc restart usługi nikomu nie daje nowej doby.

{endpoint} pokazuje bieżący stan wszystkich pięciu okien, nie zużywając żadnego z nich.

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

Zewnętrzna usługa minifikacji pozwala na 30 żądań na minutę dla całej witryny, a nie dla pojedynczego odwiedzającego. Pilnuje tego wspólny kubełek: gdy jest pusty, minifikację CSS i JS wykonuje silnik lokalny, zamiast czekać albo zwracać błąd. Pod obciążeniem pole engine może się zmieniać — wynik w obu przypadkach pozostaje poprawny.

Który silnik wykonuje pracę#

Dwie drogi, jeden kontrakt.

W chmurze — minifikacja CSS i JS

Zewnętrzna usługa minifikacji, szybka i ostrożna: usuwa te białe znaki, które można usunąć, i zachowuje te, których nie można, więc konstrukcje w rodzaju {calc} pozostają nienaruszone. Ta usługa tylko przepuszcza przez nią kod i nie dodaje nic od siebie.

Lokalny — cała reszta

Minifikacja HTML, wszystkie trzy formatery oraz minifikacja CSS/JS, gdy wspólny budżet usługi zewnętrznej się skończy albo usługa ma działać bez wywołań na zewnątrz. Zbudowany na {tools}, ładowanych dopiero wtedy, gdy potrzebuje ich żądanie — bezczynny proces pozostaje mały.

Ustaw {param}, aby przypiąć żądanie do jednej z dróg.

Co jest przechowywane#

Nic. Kod trzymany jest w pamięci przez czas trwania żądania i znika. Nie jest zapisywany na dysk i nigdy nie pojawia się w logach. Co logi rzeczywiście niosą: skrócony hash adresu IP, język, akcję, liczbę bajtów, silnik i czas trwania.