Geçen hafta sonu, bir landing page'den form gönderimlerini almak için public bir endpoint'e ihtiyacım vardı. Süslü bir şey değil — bir JSON POST kabul et, birkaç alanı validate et, makul bir cevap döndür. Tüm iş muhtemelen haftada 50 istek karşılayacaktı. 20$/aylık bir sunucu için kart bilgisi vermek, yeni bir infra aracı öğrenmek veya üç satırı her değiştirdiğimde bir CI pipeline'ı beklemek istemiyordum. Başladıktan on dakika sonra, API 300'den fazla şehirde canlıydı ve bana sıfır dolara mal oluyordu. İşte yol haritası.

Cloudflare Workers'ın gerçekten cömert bir ücretsiz katmanı var: günde 100.000 istek, kayıt olmak için kredi kartı yok ve kodun tek bir bölge yerine edge'de çalışır. Çoğu side project'in ihtiyaç duyduğu küçük API'ler için — webhook alıcıları, form handler'ları, link kısaltıcılar, JSON proxy'leri — deploy edip unutabilirsin. Bu rehber seni "Cloudflare hesabı yok"tan "curl'e cevap veren canlı URL"e yaklaşık on dakikada götürür. Gerçek bir endpoint inşa edeceğiz: bir POST kabul eden, payload'ı kontrol eden ve temiz bir cevabı geri yansıtan bir JSON validator.

Ücretsiz Olarak Ne Alıyorsun (Ve Ne Almıyorsun)

Cloudflare Workers'ın ücretsiz planı sana günde 100.000 istek ve istek başına 10 milisaniye CPU süresi verir. Çoğu JSON endpoint'inin — body'yi parse et, ufak bir iş yap, cevap döndür — rahatça 1ms'nin altında bittiğini fark edene kadar kulağa dar geliyor. 10ms tavanı CPU süresidir, wall-clock süresi değil, yani 800ms süren bir upstream fetch yine de yaklaşık 1ms CPU sayılır çünkü kodun çoğunlukla I/O bekliyordur.

Ücretsiz planda almadığın şeyler: yüksek throughput'lu kalıcı storage (Workers KV'nin kendi ücretsiz kotası var — çoğu durumda cömert, ama istek sayısından ayrı), büyük cevap payload'ları veya dakikada birden daha sık zamanlanmış cron tetikleyicileri. Veritabanına ihtiyaç duymayan tipik bir "JSON al, bir şey yap, JSON döndür" servisi için bir duvara çarpmazsın.

Kayıtta kredi kartı yok. Hesabı oluştururken, Cloudflare senden bir e-posta ve bir şifre ister — hepsi bu. Dashboard, ücretli ürünler için sonradan billing eklemeni teklif eder, ama ücretsiz Workers katmanı hiçbir şey gerektirmez ve seni bir ücretle şaşırtmaz.

Node.js ve Wrangler'ı Yükle

Wrangler, Cloudflare'in Workers için CLI'sıdır. npm üzerinden yükle — Node.js 18 veya daha yenisine ihtiyacın olacak. Eğer zaten Node'un varsa, bu tek satırlık bir iş:

bash
npm install -g wrangler

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

Şimdi giriş yap. Bu OAuth için bir tarayıcı açar, eğer yoksa Cloudflare hesabını oluşturur ve credential'ları yerel olarak saklar:

bash
wrangler login

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

Projenin İskeletini Kur

Tek bir komut ve makul varsayılanlarla bir proje iskeletin oldu — örnek bir fetch handler'ı, bir wrangler.toml config'i ve önceden bağlanmış yerel dev server'ı:

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

Generator ihtiyacın olan her şeyi tek bir klasöre koyar. src/index.js'i aç — Worker'ının çalıştırdığı dosya bu. İçeriğini varsayılan Hello World'den daha kullanışlı bir şeyle değiştireceğiz.

JSON API'yi Yaz

İşte JSON POST kabul eden, iki zorunlu alanı validate eden ve temiz bir cevap döndüren eksiksiz bir Worker. Yaygın başarısızlık modlarını — yanlış method, bozuk JSON, eksik alanlar — jenerik bir 500'e çakılmak yerine ele alır:

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

Vurgulanmaya değer iki şey. Response.json() senin için objeyi serialize eder ve Content-Type: application/json'ı ayarlar, bu yüzden header'ı hatırlamak zorunda değilsin. Ve request.json()'ı bir try/catch ile sarmalamak, Worker inşa ederken sahip olunabilecek tek en önemli alışkanlık — onsuz, bozuk bir payload kendi kodundan kullanışlı bir 400 yerine Cloudflare'in runtime'ından opak bir 500 döndürür.

Yerel Olarak Test Et

Wrangler, Cloudflare'in production'da kullandığı aynı V8 izolatını çalıştıran bir yerel dev server ile gelir. Şununla başlat:

bash
npm run dev

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

Başka bir terminalde, curl ile vur. Önce mutlu yolu dene, ardından kasten bozuk bir payload — stack trace'ler yerine temiz JSON hataları görmelisin:

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)"}
İpucu: Eğer terminalinde bir cevap garip görünüyorsa, pretty-print etmek ve incelemek için JSON Formatter'a yapıştır. Tanımadığım API'lerle çalışırken bunu günde yirmi kez yapıyorum.

Dünyaya Deploy Et — Tek Komut

Yerel çalışınca, global'e it:

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

O URL artık her Cloudflare data center'ında canlı. Berlin'den bir istek Frankfurt'a vurur, Tokyo'dan biri Tokyo'ya vurur, São Paulo'dan biri São Paulo'ya vurur — aynı kod, ekstra config yok. Bundle 1,2 KiB'ydi. Canlı URL'i yerelde kullandığın aynı curl komutlarıyla test et — sadece localhost:8787'yi Wrangler'ın yazdırdığı workers.dev hostname'iyle değiştir.

Ücretsiz Katmanı Ne Zaman Aşacaksın

Uzun bir süre, aşmayacaksın. Günde 100k istek, 24 saatlik ortalamada saniyede yaklaşık 1,15 istek demek — çoğu side project, dahili araç veya erken aşama ürünün yaptığından rahatça daha fazla. Seni ücretsiz katmandan çıkaran ilk şey genellikle istek sayısı değil, storage'dır: KV, R2 veya D1'e çok yazmaya başlarsan, onların kendi kotaları var. Ücretli plan ayda 5$'dan başlar ve sana 10 milyon istek, istek başına daha fazla CPU ve ani yüklenmeler için bir kredi kartı güvenlik ağı verir. Çoğu projenin buna asla ihtiyacı olmaz.

Sırada Ne Var

Deploy ettiğin şey, kullanışlı en az Worker'dır. Gerçek production endpoint'leri birkaç alışkanlık daha gerektirir — tarayıcı çağrıcıları için CORS, API key'ler için secrets yönetimi, yavaş upstream'ler için edge cache'leme ve upstream servisleri proxy'leme stratejisi. Bunları Cloudflare Workers ve JSON — Pratik Bir Rehber'de ele aldım, bu makalenin bittiği yerden devam ediyor.

JSON ile ilgilenen Worker'lar inşa ederken açık tuttuğum birkaç araç: cevapları pretty-print için JSON Formatter, bir payload'un neden tam olarak reddedildiğini anlamak için JSON Validator ve alan-çıkarma mantığını yazmadan önce planlamak için JSON Path. JSON formatının kendisi RFC 8259'da belirtilmiştir — gerçek kullanıcılardan garip input'ları ele almaya başladığında bir kez göz atmaya değer.

Daha derin Worker pattern'leri için — KV storage, Durable Objects, zamanlanmış tetikleyiciler, AI inference binding'leri — Cloudflare'in Workers örnek galerisi bulduğum en iyi kaynak. Sonraki adımlar için kopyala-yapıştır tarif listesi.

Toparlayalım

Cloudflare Workers, gerçek side project'ler için fiilen uygulanabilir o nadir ücretsiz katmanlardan biri. Başlamak için kredi kartı yok, günde 100k istek ve tek bir komuta sığan bir deploy hikayesi. Bu makaledeki pattern — JSON kabul et, validate et, JSON döndür — çoğu API'nin yaptığı şeyin şaşırtıcı bir kısmını kapsıyor. Eğer küçük bir API'yi yayına almayı, infra angarya gibi geldiği için erteliyorduysan, bu üç yıl önce keşke gitseydim dediğim yol.

← All JSON articles Browse all categories →