Documentazione dell’API

Avvio rapido#

Minifica un foglio di stile e stampa il risultato:

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

Sostituisci {css} con {js} o {html}, e {minify} con {beautify}. Ogni combinazione funziona.

Endpoint#

L’indirizzo di base è {base}. Tutto ciò che segue è un POST, se non indicato diversamente.

{lang} è css, js oppure html.

Inviare il codice#

Su ogni endpoint sono accettate tre forme di corpo — scegli quella che il tuo client rende più semplice.

Codificato come modulo

Un campo {input}, {type}. È la forma che le API di minificazione accettano per convenzione, quindi uno script esistente cambia solo indirizzo.

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

JSON

{type} con una stringa {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

Corpo grezzo

Qualsiasi altro content type: il corpo è il codice. Comodo per {example}.

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

Dimensione

2 MB per richiesta. Tutto ciò che è più grande torna come 413 senza essere letto.

Parametri di query#

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

La risposta#

Una chiamata riuscita restituisce 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}"
}

Risposte in testo semplice#

Aggiungi {raw} a un qualsiasi endpoint di formattazione e il corpo è il risultato e nient’altro, come {type}. Le intestazioni restano le stesse. Utile quando a chiamare è una shell:

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

Intestazioni della risposta#

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

Errori#

Ogni errore è JSON nella forma consueta per un’API di questo tipo, quindi un client che già gestisce quella forma gestisce anche i nostri:

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

Limiti di frequenza#

Per indirizzo IP, cinque finestre scorrevoli, applicate tutte insieme. Una richiesta deve stare in tutte e cinque.

Quando una finestra è esaurita la risposta è 429 con un’intestazione Retry-After che indica i secondi mancanti alla riapertura della più stretta. Nulla viene messo in coda.

I contatori stanno in un piccolo database su disco, quindi riavviare il servizio non regala a nessuno una giornata nuova.

{endpoint} riporta lo stato attuale di tutte e cinque le finestre senza consumarne una.

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

Il servizio esterno di minificazione consente 30 richieste al minuto per l’intero sito, non per visitatore. Un token bucket condiviso ne tiene il conto: quando è vuoto, la minificazione di CSS e JS viene servita dal motore locale invece di attendere o fallire. Sotto carico puoi vedere il campo engine cambiare — l’output resta valido in entrambi i casi.

Quale motore fa il lavoro#

Due percorsi, un solo contratto.

Cloud — minificazione di CSS e JS

Un servizio esterno di minificazione, veloce e prudente: toglie gli spazi che si possono togliere e mantiene quelli che non si possono, così che un {calc} resti intatto. Questo servizio fa passare il codice e non aggiunge nulla di suo.

Locale — tutto il resto

Minificazione HTML, tutti e tre i formattatori e la minificazione di CSS/JS ogni volta che il budget condiviso del servizio esterno è finito o il servizio è impostato per restare offline. Costruito su {tools}, caricati solo quando una richiesta li richiede, così che un processo inattivo resti leggero.

Imposta {param} per fissare una richiesta su un solo percorso.

Che cosa viene conservato#

Nulla. Il codice resta in memoria per la durata della richiesta e poi viene scartato. Non viene scritto su disco e non compare mai in un log. Quello che i log contengono davvero: un hash troncato dell’IP, il linguaggio, l’azione, il conteggio dei byte, il motore e la durata.