API documentation

Quick start#

Minify a stylesheet and print the result:

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}

Swap {css} for {js} or {html}, and {minify} for {beautify}. Every combination works.

Endpoints#

The base address is {base}. Everything below is a POST unless it says otherwise.

{lang} is one of css, js or html.

Sending the code#

Three body shapes are accepted on every endpoint — pick whichever your client makes easy.

Form encoded

An {input} field, {type}. This is the shape Toptal's own minifiers take, so an existing script only changes its address.

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

JSON

{type} with an {input} string.

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

Raw body

Any other content type: the body is the code. Convenient for {example}.

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

Size

2 MB per request. Anything larger comes back as 413 without being read.

Query parameters#

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

The response#

A successful call returns 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}"
}

Plain-text responses#

Append {raw} to any format endpoint and the body is the result and nothing else, as {type}. The headers are the same. Useful when the caller is a shell:

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

Response headers#

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

Errors#

Every error is JSON in the same shape Toptal's minifiers use, so a client that already handles theirs handles ours:

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

Rate limits#

Per IP address, five rolling windows, all enforced at once. A request has to fit in all five.

When a window is spent the answer is 429 with a Retry-After header giving the seconds until the tightest one reopens. Nothing is queued.

The counters live in a small database on disk, so restarting the service does not hand anyone a fresh day.

{endpoint} reports the current state of all five windows without spending one.

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

Toptal allows 30 requests a minute for this whole service, not per visitor. A shared bucket tracks that: when it is empty, CSS and JS minification is served by the local engine instead of waiting or failing. You may see the engine field change under load — the output stays valid either way.

Which engine does the work#

Two paths, one contract.

Toptal — CSS and JS minification

Their minifiers are fast and conservative: they drop the whitespace that can go and keep the whitespace that cannot, so things like {calc} survive intact. This service passes the code through and adds nothing of its own.

Local — everything else

HTML minification, all three beautifiers, and CSS/JS minification whenever the shared upstream budget is gone or the service is set to stay offline. Built on {tools}, loaded only when a request needs them so an idle process stays small.

Set {param} to pin a request to one path.

What is kept#

Nothing. The code is held in memory for the length of the request and dropped. It is not written to disk and never appears in a log. What the logs do carry: a truncated hash of the IP, the language, the action, the byte count, the engine and the duration.