Documentation de l’API

Démarrage rapide#

Minifier une feuille de style et afficher le résultat :

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}

Remplacez {css} par {js} ou {html}, et {minify} par {beautify}. Toutes les combinaisons fonctionnent.

Points de terminaison#

L’adresse de base est {base}. Tout ce qui suit est un POST, sauf mention contraire.

{lang} vaut css, js ou html.

Envoyer le code#

Trois formes de corps sont acceptées sur chaque point de terminaison — prenez celle que votre client rend la plus simple.

Encodé en formulaire

Un champ {input}, {type}. C’est la forme qu’attendent les minificateurs de Toptal : un script existant n’a qu’à changer d’adresse.

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

JSON

{type} avec une chaîne {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

Corps brut

Tout autre type de contenu : le corps est le code. Pratique pour {example}.

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

Taille

2 Mo par requête. Tout ce qui dépasse revient en 413 sans être lu.

Paramètres de requête#

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

La réponse#

Un appel réussi renvoie du 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}"
}

Réponses en texte brut#

Ajoutez {raw} à n’importe quel point de terminaison de formatage et le corps est le résultat, rien d’autre, en {type}. Les en-têtes sont les mêmes. Utile quand l’appelant est un shell :

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

En-têtes de réponse#

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

Erreurs#

Chaque erreur est du JSON, dans la même forme que celle des minificateurs de Toptal — un client qui gère déjà les leurs gère les nôtres :

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

Limites de débit#

Par adresse IP, cinq fenêtres glissantes, toutes appliquées en même temps. Une requête doit tenir dans les cinq.

Quand une fenêtre est épuisée, la réponse est un 429 avec un en-tête Retry-After donnant les secondes avant la réouverture de la plus stricte. Rien n’est mis en file d’attente.

Les compteurs vivent dans une petite base de données sur disque : redémarrer le service n’offre à personne une journée neuve.

{endpoint} rapporte l’état courant des cinq fenêtres sans en consommer une.

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

Toptal autorise 30 requêtes par minute pour l’ensemble du service, et non par visiteur. Un seau de jetons partagé en tient le compte : lorsqu’il est vide, la minification CSS et JS est assurée par le moteur local plutôt que d’attendre ou d’échouer. Le champ engine peut donc changer sous la charge — la sortie reste valide dans les deux cas.

Quel moteur fait le travail#

Deux chemins, un seul contrat.

Toptal — minification CSS et JS

Leurs minificateurs sont rapides et prudents : ils suppriment les espaces qui peuvent partir et gardent ceux qui ne le peuvent pas, si bien qu’un {calc} reste intact. Ce service se contente de faire passer le code, sans rien y ajouter.

Local — tout le reste

La minification HTML, les trois formateurs, et la minification CSS/JS dès que le budget amont partagé est épuisé ou que le service est réglé pour rester hors ligne. Construit sur {tools}, chargés seulement quand une requête en a besoin, pour qu’un processus au repos reste petit.

Réglez {param} pour fixer une requête sur un seul chemin.

Ce qui est conservé#

Rien. Le code reste en mémoire le temps de la requête, puis est abandonné. Il n’est pas écrit sur disque et n’apparaît jamais dans un journal. Ce que les journaux portent, en revanche : un hachage tronqué de l’IP, le langage, l’action, le nombre d’octets, le moteur et la durée.