Afgelopen weekend had ik een publiek endpoint nodig om form-submissions te ontvangen vanaf een landings- pagina. Niets bijzonders — accepteer een JSON POST, valideer een paar velden, geef een fatsoenlijke response terug. Het hele ding zou misschien 50 requests per week afhandelen. Ik wilde geen creditcard achterlaten voor een server van $20/maand, geen nieuwe infra-tool leren, en niet bij elke drie regels code een CI-pipeline afwachten. Tien minuten nadat ik begon, was de API live in 300+ steden en kostte hij me nul dollar. Dit is de walkthrough.

Cloudflare Workers heeft een gratis tier die werkelijk royaal is: 100.000 requests per dag, geen creditcard nodig om je in te schrijven, en je code draait aan de edge in plaats van in één regio. Voor de kleine API's die de meeste side-projects nodig hebben — webhook-ontvangers, form-handlers, link-shorteners, JSON-proxies — kun je deployen en het vergeten. Deze gids brengt je van "geen Cloudflare-account" naar "live URL die reageert op curl" in ongeveer tien minuten. We bouwen een echt endpoint: een JSON-validator die een POST accepteert, de payload checkt, en een nette response terug echoot.

Wat je gratis krijgt (en wat niet)

Het gratis plan van Cloudflare Workers geeft je 100.000 requests per dag en 10 milliseconden CPU-tijd per request. Dat klinkt krap totdat je beseft dat de meeste JSON-endpoints — body parsen, een minuscuul beetje werk doen, een response teruggeven — ruim onder 1ms klaar zijn. Het 10ms-plafond is CPU-tijd, niet wall-clock-tijd, dus een upstream-fetch die 800ms duurt telt nog steeds als ongeveer 1ms CPU omdat je code voornamelijk op I/O wacht.

Wat je niet krijgt op het gratis plan: persistente storage met hoge throughput (Workers KV heeft zijn eigen gratis quota — royaal voor de meeste gevallen, maar los van de request-telling), grote response-payloads, of geplande cron-triggers vaker dan eens per minuut. Voor een typische "ontvang JSON, doe iets, geef JSON terug"-service die geen database nodig heeft, loop je niet tegen een muur op.

Geen creditcard bij signup. Wanneer je het account aanmaakt, vraagt Cloudflare om een e-mail en een wachtwoord — dat is alles. De dashboard vraagt je later wel om billing toe te voegen voor betaalde producten, maar de gratis Workers-tier heeft niets nodig en zal je niet verrassen met een afschrijving.

Installeer Node.js en Wrangler

Wrangler is Cloudflare's CLI voor Workers. Installeer hem via npm — je hebt Node.js 18 of nieuwer nodig. Als je al Node hebt, is dit een one-liner:

bash
npm install -g wrangler

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

Nu inloggen. Dit opent een browser voor OAuth, maakt het Cloudflare-account aan als je er nog geen hebt, en bewaart de credentials lokaal:

bash
wrangler login

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

Het project scaffolden

Eén commando en je hebt een projectskelet met zinnige defaults — een voorbeeld fetch-handler, een wrangler.toml-config, en de lokale dev-server al ingeregeld:

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

De generator zet alles wat je nodig hebt in één map. Open src/index.js — dat is het bestand dat je Worker draait. We vervangen de inhoud door iets nuttigers dan de standaard Hello World.

Schrijf de JSON-API

Hier is een complete Worker die een JSON POST accepteert, twee verplichte velden valideert, en een nette response teruggeeft. Hij handelt de gangbare faalmodi af — verkeerde method, misvormde JSON, ontbrekende velden — in plaats van te crashen naar een generieke 500:

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 },
    });
  },
};

Twee dingen om uit te lichten. Response.json() serialiseert het object en zet Content-Type: application/json voor je, dus je hoeft de header niet te onthouden. En request.json() in een try/catch wikkelen is de allerbelangrijkste gewoonte bij het bouwen van Workers — zonder dat geeft een misvormde payload een ondoorzichtige 500 vanuit Cloudflare's runtime in plaats van een nuttige 400 vanuit jouw code.

Test het lokaal

Wrangler komt met een lokale dev-server die hetzelfde V8-isolate draait dat Cloudflare in productie gebruikt. Start hem met:

bash
npm run dev

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

Sla in een andere terminal toe met curl. Probeer eerst de happy path, daarna een bewust kapotte payload — je zou nette JSON-fouten moeten zien in plaats van 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)"}
Tip: als een response er raar uitziet in je terminal, plak hem in de JSON Formatter om pretty te printen en te inspecteren. Ik doe dit twintig keer per dag bij het werken met onbekende API's.

Deploy naar de wereld — één commando

Als lokaal werkt, push je het wereldwijd:

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: ...

Die URL is nu live op elk Cloudflare-datacenter. Een request uit Berlijn raakt Frankfurt, één uit Tokyo raakt Tokyo, één uit São Paulo raakt São Paulo — dezelfde code, geen extra config. De bundle was 1,2 KiB. Test de live URL met dezelfde curl-commando's die je lokaal gebruikte — wissel alleen localhost:8787 voor de workers.dev-hostname die Wrangler heeft afgedrukt.

Wanneer je het gratis tier ontgroeit

Lange tijd doe je dat niet. 100k requests per dag is ongeveer 1,15 requests per seconde gemiddeld over 24 uur — comfortabel meer dan de meeste side-projects, interne tools of early-stage producten doen. Het eerste dat je doorgaans van het gratis tier af duwt is niet de request-telling maar storage: als je veel naar KV, R2 of D1 begint te schrijven, hebben die hun eigen quota. Het betaalde plan begint bij $5/maand en geeft je 10 miljoen requests, meer CPU per request, en een creditcard- vangnet voor pieken. De meeste projecten hebben het nooit nodig.

Wat nu

Wat je hebt uitgerold is de minimale nuttige Worker. Echte productie-endpoints hebben een paar gewoontes meer nodig — CORS voor browser-callers, secrets management voor API-keys, edge-caching voor trage upstreams, en een strategie voor het proxyen van upstream-services. Die behandelde ik in Cloudflare Workers en JSON — een praktische gids, die oppikt waar dit artikel eindigt.

Een paar tools die ik open houd terwijl ik Workers bouw die met JSON omgaan: JSON Formatter voor het pretty-printen van responses, JSON Validator om uit te vinden waarom een payload precies werd afgewezen, en JSON Path om field-extractie-logica te plannen voordat je hem schrijft. Het JSON-formaat zelf is gespecificeerd in RFC 8259 — een snelle scan waard zodra je rare input van echte gebruikers begint te verwerken.

Voor diepere Worker-patronen — KV-storage, Durable Objects, geplande triggers, de AI-inference-bindings — is Cloudflare's Workers-voorbeeldengallerij de beste resource die ik heb gevonden. Het is een copy-pasteable lijst recepten voor de volgende stappen.

Afronding

Cloudflare Workers is het zeldzame gratis tier dat werkelijk bruikbaar is voor echte side- projects. Geen creditcard om te beginnen, 100k requests per dag, en een deploy-verhaal dat in één commando past. Het patroon in dit artikel — JSON accepteren, valideren, JSON teruggeven — dekt een verrassend deel van wat de meeste API's doen. Als je hebt zitten talmen met een kleine API omdat de infra als een klus voelde, is dit het pad dat ik wou dat ik drie jaar geleden had genomen.

← All JSON articles Browse all categories →