Letztes Wochenende brauchte ich einen öffentlichen Endpoint, um Formular-Submissions von einer Landing Page zu empfangen. Nichts Aufwendiges — einen JSON-POST annehmen, ein paar Felder validieren, eine sinnvolle Antwort zurückgeben. Das Ganze würde vielleicht 50 Requests pro Woche verarbeiten. Ich wollte keine Kreditkarte für einen 20-Dollar-Server hinterlegen, kein neues Infra-Tool lernen, und nicht jedes Mal eine CI-Pipeline durchlaufen, wenn ich drei Zeilen ändere. Zehn Minuten nach dem Start war die API in über 300 Städten live und kostete mich null Dollar. Das ist das Walkthrough.

Cloudflare Workers hat einen Free Tier, der tatsächlich großzügig ist: 100.000 Requests pro Tag, keine Kreditkarte für die Anmeldung nötig, und dein Code läuft am Edge statt in einer Region. Für die kleinen APIs, die die meisten Side Projects brauchen — Webhook-Receiver, Form-Handler, Link-Shortener, JSON-Proxies — kannst du shippen und vergessen. Dieser Guide bringt dich von "kein Cloudflare-Account" zu "Live-URL antwortet auf curl" in etwa zehn Minuten. Wir bauen einen echten Endpoint: einen JSON-Validator, der einen POST annimmt, den Payload prüft und eine saubere Antwort zurückgibt.

Was du gratis bekommst (und was nicht)

Der Free Plan von Cloudflare Workers gibt dir 100.000 Requests pro Tag und 10 Millisekunden CPU-Zeit pro Request. Klingt knapp, bis dir auffällt, dass die meisten JSON-Endpoints — Body parsen, ein bisschen Arbeit, Antwort zurück — deutlich unter 1ms fertig sind. Die 10ms-Grenze ist CPU-Zeit, nicht Wall-Clock-Zeit, also zählt ein Upstream-Fetch, der 800ms dauert, immer noch nur als ungefähr 1ms CPU, weil dein Code die meiste Zeit auf I/O wartet.

Was du im Free Plan nicht bekommst: persistenten Speicher mit hohem Durchsatz (Workers KV hat sein eigenes Free-Kontingent — großzügig für die meisten Fälle, aber getrennt von der Request-Zahl), große Response-Payloads, oder Cron-Trigger öfter als einmal pro Minute. Für einen typischen "JSON empfangen, was machen, JSON zurück"-Service ohne Datenbank rennst du nicht gegen eine Wand.

Keine Kreditkarte bei der Anmeldung. Wenn du den Account erstellst, fragt Cloudflare nach E-Mail und Passwort — das war's. Das Dashboard fordert dich später auf, Zahlungsdaten für bezahlte Produkte hinzuzufügen, aber der Free Tier von Workers braucht nichts und überrascht dich nicht mit einer Rechnung.

Node.js und Wrangler installieren

Wrangler ist die Cloudflare-CLI für Workers. Installiere sie via npm — du brauchst Node.js 18 oder neuer. Wenn du Node schon hast, ist das ein Einzeiler:

bash
npm install -g wrangler

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

Jetzt einloggen. Das öffnet einen Browser für OAuth, legt den Cloudflare-Account an, falls du keinen hast, und speichert die Credentials lokal:

bash
wrangler login

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

Das Projekt anlegen

Ein Befehl und du hast ein Projektgerüst mit sinnvollen Defaults — ein Beispiel-fetch-Handler, eine wrangler.toml-Config, und der lokale Dev-Server ist schon verdrahtet:

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

Der Generator wirft alles, was du brauchst, in einen Ordner. Öffne src/index.js — das ist die Datei, die dein Worker ausführt. Wir ersetzen den Inhalt durch etwas Nützlicheres als das Standard-Hello-World.

Die JSON-API schreiben

Hier ist ein kompletter Worker, der einen JSON-POST annimmt, zwei Pflichtfelder validiert und eine saubere Antwort zurückgibt. Er behandelt die üblichen Fehlermodi — falsche Methode, malformed JSON, fehlende Felder — statt in einer generischen 500 abzuschmieren:

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

Zwei Dinge sind erwähnenswert. Response.json() serialisiert das Objekt und setzt Content-Type: application/json für dich, du musst dich also nicht um den Header kümmern. Und request.json() in ein try/catch zu wickeln, ist die wichtigste einzelne Gewohnheit beim Worker-Bau — ohne das gibt ein malformed Payload eine undurchsichtige 500 aus Cloudflares Runtime zurück statt einer nützlichen 400 aus deinem Code.

Lokal testen

Wrangler bringt einen lokalen Dev-Server mit, der dasselbe V8-Isolate fährt, das Cloudflare in Produktion verwendet. Starte ihn mit:

bash
npm run dev

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

In einem zweiten Terminal feuerst du mit curl drauf. Probier zuerst den Happy Path, dann ein absichtlich kaputtes Payload — du solltest saubere JSON-Fehler sehen statt 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)"}
Tipp: Wenn eine Antwort im Terminal komisch aussieht, kipp sie in den JSON Formatter, um sie schön ausgegeben zu inspizieren. Ich mache das zwanzig Mal am Tag, wenn ich mit unbekannten APIs arbeite.

Deploy in die Welt — ein Befehl

Wenn lokal läuft, schick es global raus:

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

Diese URL ist jetzt in jedem Cloudflare-Rechenzentrum live. Ein Request aus Berlin trifft Frankfurt, einer aus Tokio trifft Tokio, einer aus São Paulo trifft São Paulo — derselbe Code, keine extra Config. Das Bundle war 1,2 KiB groß. Teste die Live-URL mit denselben curl-Befehlen, die du lokal benutzt hast — tausch einfach localhost:8787 gegen den workers.dev-Hostname, den Wrangler ausgegeben hat.

Wann du den Free Tier sprengst

Lange Zeit gar nicht. 100k Requests/Tag sind im 24-Stunden-Schnitt etwa 1,15 Requests pro Sekunde — bequem mehr, als die meisten Side Projects, internen Tools oder Produkte in der Frühphase machen. Was dich normalerweise zuerst aus dem Free Tier drückt, ist nicht die Request-Anzahl, sondern Speicher: wenn du anfängst, viel in KV, R2 oder D1 zu schreiben, haben die ihre eigenen Kontingente. Der Bezahl-Plan startet bei 5 USD/Monat und gibt dir 10 Millionen Requests, mehr CPU pro Request und ein Kreditkarten-Sicherheitsnetz für Spitzen. Die meisten Projekte brauchen ihn nie.

Was als nächstes kommt

Was du grade ausgeliefert hast, ist der minimale brauchbare Worker. Echte Production-Endpoints brauchen ein paar weitere Gewohnheiten — CORS für Browser-Aufrufer, Secrets-Verwaltung für API-Keys, Edge-Caching für langsame Upstreams und eine Strategie zum Proxyen von Upstream-Diensten. Das habe ich in Cloudflare Workers und JSON — Ein Praxisleitfaden behandelt, der genau da anschließt, wo dieser Artikel aufhört.

Ein paar Tools, die ich offen halte, wenn ich Workers baue, die mit JSON arbeiten: JSON Formatter zum schönen Ausgeben von Responses, JSON Validator, um herauszufinden, warum ein Payload genau abgelehnt wurde, und JSON Path, um die Field-Extraction-Logik zu planen, bevor ich sie schreibe. Das JSON-Format selbst ist in RFC 8259 spezifiziert — einen Blick wert, sobald du anfängst, mit komischen Inputs von echten Nutzern umzugehen.

Für tiefere Worker-Patterns — KV-Speicher, Durable Objects, geplante Trigger, die AI-Inference-Bindings — ist Cloudflares Workers Examples Gallery die beste Ressource, die ich gefunden habe. Eine Copy-paste-fähige Liste von Rezepten für die nächsten Schritte.

Fazit

Cloudflare Workers ist der seltene Free Tier, der für echte Side Projects tatsächlich tragfähig ist. Keine Kreditkarte zum Start, 100k Requests pro Tag, und eine Deploy-Story, die in einen einzigen Befehl passt. Das Pattern aus diesem Artikel — JSON empfangen, validieren, JSON zurückgeben — deckt überraschend viel ab von dem, was die meisten APIs tun. Wenn du das Ausliefern einer kleinen API verschoben hast, weil sich die Infrastruktur wie eine Plackerei anfühlte, ist das der Weg, den ich vor drei Jahren gerne gegangen wäre.

← All JSON articles Browse all categories →