Le week-end dernier, j'avais besoin d'un endpoint public pour recevoir les soumissions de formulaire d'une landing page. Rien de fou — accepter un POST JSON, valider quelques champs, retourner une réponse correcte. L'ensemble traiterait peut-être 50 requêtes par semaine. Je ne voulais pas mettre une carte de crédit en banque pour un serveur à 20 $/mois, apprendre un nouvel outil d'infra, ni attendre une pipeline de CI à chaque fois que je modifiais trois lignes. Dix minutes après avoir commencé, l'API tournait en direct dans plus de 300 villes et me coûtait zéro dollar. Voici la marche à suivre.

Cloudflare Workers propose un palier gratuit qui est réellement généreux : 100 000 requêtes par jour, pas de carte de crédit nécessaire pour s'inscrire, et votre code s'exécute en périphérie au lieu d'une seule région. Pour les petites API dont la plupart des side projects ont besoin — récepteurs de webhooks, gestionnaires de formulaires, raccourcisseurs de liens, proxys JSON — vous pouvez livrer et oublier. Ce guide vous fait passer de « pas de compte Cloudflare » à « URL en ligne qui répond à curl » en environ dix minutes. Nous allons construire un vrai endpoint : un validateur JSON qui accepte un POST, vérifie le payload, et renvoie une réponse propre.

Ce que vous obtenez gratuitement (et ce que vous n'obtenez pas)

Le plan gratuit de Cloudflare Workers vous donne 100 000 requêtes par jour et 10 millisecondes de temps CPU par requête. Cela paraît serré jusqu'à ce que vous réalisiez que la plupart des endpoints JSON — parser un corps, faire un peu de travail, retourner une réponse — finissent largement en moins d'1 ms. Le plafond de 10 ms est du temps CPU, pas du wall-clock, donc un fetch upstream qui prend 800 ms compte toujours pour environ 1 ms de CPU parce que votre code attend essentiellement sur des I/O.

Ce que vous n'obtenez pas avec le plan gratuit : du stockage persistant à fort débit (Workers KV a son propre quota gratuit — généreux pour la plupart des cas, mais distinct du compteur de requêtes), de gros payloads de réponse, ou des triggers cron planifiés plus souvent qu'une fois par minute. Pour un service typique « recevoir du JSON, faire un truc, retourner du JSON » qui n'a pas besoin de base de données, vous ne taperez pas dans un mur.

Pas de carte de crédit à l'inscription. Quand vous créez le compte, Cloudflare demande un email et un mot de passe — c'est tout. Le dashboard vous demande bien d'ajouter de la facturation plus tard pour des produits payants, mais le palier gratuit Workers n'a besoin de rien et ne vous surprendra pas avec un débit.

Installer Node.js et Wrangler

Wrangler est la CLI de Cloudflare pour Workers. Installez-la via npm — vous aurez besoin de Node.js 18 ou plus récent. Si vous avez déjà Node, c'est une commande en une ligne :

bash
npm install -g wrangler

# Verify
wrangler --version
# Should print 3.x or higher

Connectez-vous maintenant. Cela ouvre un navigateur pour OAuth, crée le compte Cloudflare si vous n'en avez pas, et stocke les identifiants localement :

bash
wrangler login

# Opens https://dash.cloudflare.com/oauth/authorize ...
# After you approve: "Successfully logged in."

Échafauder le projet

Une commande et vous avez un squelette de projet avec des valeurs par défaut sensées — un handler fetch d'exemple, une config wrangler.toml, et le serveur de dev local déjà câblé :

bash
npm create cloudflare@latest free-json-api

# When prompted, pick:
#   "Hello World" Worker
#   JavaScript (or TypeScript — your call)
#   No deploy yet (we'll do that ourselves)

cd free-json-api

Le générateur dépose tout ce dont vous avez besoin dans un seul dossier. Ouvrez src/index.js — c'est le fichier que votre Worker exécute. Nous allons remplacer son contenu par quelque chose de plus utile que le Hello World par défaut.

Écrire l'API JSON

Voici un Worker complet qui accepte un POST JSON, valide deux champs requis, et retourne une réponse propre. Il gère les modes de défaillance courants — mauvaise méthode, JSON malformé, champs manquants — au lieu de crasher en 500 générique :

js
export default {
  async fetch(request) {
    if (request.method !== 'POST') {
      return Response.json(
        { error: 'POST only' },
        { status: 405 },
      );
    }

    let body;
    try {
      body = await request.json();
    } catch {
      return Response.json(
        { error: 'Body must be valid JSON' },
        { status: 400 },
      );
    }

    const { email, message } = body;
    if (typeof email !== 'string' || typeof message !== 'string') {
      return Response.json(
        { error: 'email and message are required (strings)' },
        { status: 422 },
      );
    }

    return Response.json({
      ok: true,
      receivedAt: new Date().toISOString(),
      echo: { email, message },
    });
  },
};

Deux points méritent d'être soulignés. Response.json() sérialise l'objet et règle Content-Type: application/json pour vous, donc vous n'avez pas à vous souvenir de l'en-tête. Et envelopper request.json() dans un try/catch est l'habitude la plus importante quand vous construisez des Workers — sans elle, un payload malformé retourne un 500 opaque depuis le runtime de Cloudflare au lieu d'un 400 utile depuis votre code.

Le tester localement

Wrangler est livré avec un serveur de dev local qui exécute le même isolat V8 que Cloudflare utilise en production. Démarrez-le avec :

bash
npm run dev

# ⛅️ wrangler 3.x
# [wrangler:inf] Ready on http://localhost:8787

Dans un autre terminal, attaquez-le avec curl. Essayez d'abord le chemin heureux, puis un payload délibérément cassé — vous devriez voir des erreurs JSON propres au lieu de stack traces :

bash
# Happy path
curl -X POST http://localhost:8787 \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","message":"hello"}'

# {"ok":true,"receivedAt":"2025-10-15T...","echo":{...}}

# Broken JSON (note the missing closing brace)
curl -X POST http://localhost:8787 \
  -H "Content-Type: application/json" \
  -d '{"email": "ava"'

# {"error":"Body must be valid JSON"}

# Missing required field
curl -X POST http://localhost:8787 \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]"}'

# {"error":"email and message are required (strings)"}
Astuce : si une réponse a l'air bizarre dans votre terminal, collez-la dans le JSON Formatter pour la formater joliment et l'inspecter. Je fais ça vingt fois par jour quand je travaille avec des API peu familières.

Déployer sur le monde — une seule commande

Quand le local fonctionne, poussez-le en global :

bash
npx wrangler deploy

# Total Upload: 1.18 KiB / gzip: 0.55 KiB
# Uploaded free-json-api (1.34 sec)
# Published free-json-api (4.21 sec)
#   https://free-json-api.<your-subdomain>.workers.dev
# Current Deployment ID: ...

Cette URL est maintenant en ligne dans tous les centres de données Cloudflare. Une requête depuis Berlin frappe Francfort, une depuis Tokyo frappe Tokyo, une depuis São Paulo frappe São Paulo — même code, pas de config supplémentaire. Le bundle faisait 1,2 KiB. Testez l'URL en ligne avec les mêmes commandes curl que vous avez utilisées localement — remplacez juste localhost:8787 par le hostname workers.dev que Wrangler a affiché.

Quand vous dépasserez le palier gratuit

Pendant longtemps, ça n'arrivera pas. 100k requêtes/jour, c'est environ 1,15 requête par seconde en moyenne sur 24 heures — confortablement plus que ce que font la plupart des side projects, outils internes ou produits en phase précoce. La première chose qui vous pousse généralement hors du palier gratuit, ce n'est pas le nombre de requêtes mais le stockage : si vous commencez à beaucoup écrire dans KV, R2 ou D1, ceux-ci ont leurs propres quotas. Le plan payant démarre à 5 $/mois et vous donne 10 millions de requêtes, plus de CPU par requête, et un filet de sécurité par carte de crédit pour les pics. La plupart des projets n'en ont jamais besoin.

Et après

Ce que vous avez livré, c'est le minimum utile d'un Worker. Les vrais endpoints en production nécessitent quelques habitudes supplémentaires — CORS pour les appelants navigateur, gestion des secrets pour les clés d'API, mise en cache en périphérie pour les upstreams lents, et une stratégie pour proxyfier les services upstream. J'ai couvert ça dans Cloudflare Workers et JSON — Un guide pratique, qui reprend là où cet article s'arrête.

Quelques outils que je garde ouverts en construisant des Workers qui manipulent du JSON : JSON Formatter pour formater joliment les réponses, JSON Validator pour comprendre exactement pourquoi un payload a été rejeté, et JSON Path pour planifier la logique d'extraction de champs avant de l'écrire. Le format JSON lui-même est spécifié dans RFC 8259 — qui mérite un coup d'œil dès que vous commencez à gérer des entrées bizarres venant de vrais utilisateurs.

Pour des patterns Worker plus poussés — stockage KV, Durable Objects, triggers planifiés, les bindings d'inférence AI — la galerie d'exemples Workers de Cloudflare est la meilleure ressource que j'ai trouvée. C'est une liste copy-pasteable de recettes pour les étapes suivantes.

Pour conclure

Cloudflare Workers est ce rare palier gratuit qui est réellement viable pour de vrais side projects. Pas de carte de crédit pour démarrer, 100k requêtes par jour, et une histoire de déploiement qui tient en une seule commande. Le pattern de cet article — accepter du JSON, valider, retourner du JSON — couvre une quantité étonnante de ce que font la plupart des API. Si vous reportez la livraison d'une petite API parce que l'infra vous semblait être une corvée, c'est le chemin que j'aurais aimé prendre il y a trois ans.

← All JSON articles Browse all categories →