Edge tarafında API fikri neden bu kadar popüler?
Klasik yaklaşımda bir JSON API’yi bir sunucuda (VPS, container, PaaS) çalıştırır, ölçekleme ve gecikme sorunlarını ayrı ayrı yönetirsiniz. Cloudflare Workers ise kodunuzu kullanıcıya daha yakın “edge” noktalarında çalıştırarak düşük gecikme, otomatik ölçeklenme ve yönetim kolaylığı sunar. Bu yazıda, güncel ve ileri seviye bir senaryo olarak Cloudflare Workers ile minimal bir JSON API kuracak, ardından JWT doğrulama ekleyerek endpoint’leri koruma altına alacağız.
Ön koşullar
Bu öğretici için bir Cloudflare hesabı, Node.js (tercihen LTS) ve Cloudflare’ın CLI aracı Wrangler gerekli. Ayrıca JWT üretmek için bir kimlik sağlayıcı (Auth0, Firebase, Keycloak vb.) kullanabilirsiniz; ancak burada doğrulama kısmını Workers üzerinde ele alacağız. Amaç, “Authorization: Bearer ...” başlığıyla gelen token’ı doğrulayıp yetkisiz istekleri reddetmek.
1) Projeyi oluşturma (Wrangler)
Yerel ortamda yeni bir Worker projesi başlatın. Wrangler, TypeScript ve modern Worker runtime’ı ile hızlı bir iskelet oluşturur. Terminalde proje klasörünü oluşturduktan sonra geliştirme sunucusunu ayağa kaldırarak endpoint’leri test edebilirsiniz. Buradaki kritik nokta: Worker kodu Node.js sunucusu gibi “stateful” değildir; tasarımınızı stateless düşünmek daha doğru sonuç verir.
2) JSON API: Basit bir route yapısı
Workers ortamında istekleri fetch handler’ı ile karşılarız. Birkaç route ile başlayalım: /health (servis kontrolü), /api/profile (JWT gerektiren örnek endpoint). Aşağıdaki örnek, JSON cevapları standartlaştırmak için küçük yardımcı fonksiyonlar kullanır.
Örnek Worker kodu (TypeScript mantığı):
Not: Kod örneğini kendi projenize göre uyarlayın; özellikle JWT doğrulama için kullanacağınız public key veya JWKS adresi değişecektir.
Route mantığı: /health herkese açık, /api/profile ise Bearer token ister. Token doğrulanırsa örnek bir profil JSON’u döner.
3) JWT doğrulama: HS256 yerine RS256/JWKS yaklaşımı
Güncel pratikte JWT doğrulamada iki ana yol var: paylaşılan gizli anahtar (HS256) veya asimetrik anahtar (RS256/ES256). Üretim ortamında, özellikle üçüncü parti kimlik sağlayıcıları ile, JWKS (JSON Web Key Set) üzerinden public key çekip doğrulama yapmak daha sürdürülebilir bir yöntemdir. Böylece anahtar rotasyonu kimlik sağlayıcı tarafında yönetilir ve Worker sadece güncel anahtarı kullanır.
Workers içinde JWKS kullanırken iki konu önem kazanır: cache ve performans. Her istekte JWKS çekmek gecikmeyi artırır. Bu yüzden JWKS yanıtını belirli bir süre cache’lemek gerekir. Cloudflare Workers, Cache API ile bu işi oldukça pratik hale getirir. Alternatif olarak KV ya da D1 gibi çözümler de kullanılabilir, fakat JWKS için Cache API genellikle yeterlidir.
4) Güvenlik kontrol listesi (pratik öneriler)
Audience (aud) ve issuer (iss) doğrulaması yapın. Sadece imza doğrulamak yetmez; token’ın kimin için üretildiğini ve hangi otorite tarafından imzalandığını da kontrol etmek gerekir. Ayrıca token süresi için exp kontrolü zorunludur. Saat kayması ihtimaline karşı küçük bir tolerans (clock skew) eklemek sahada hataları azaltır.
CORS konusu da sık atlanır. API’niz tarayıcıdan çağrılacaksa doğru origin’leri whitelist ederek “*” kullanımını sınırlayın. Workers, preflight (OPTIONS) isteklerini yönetmek için idealdir. Ek olarak rate limit için Cloudflare’ın WAF ve Rate Limiting özellikleri veya uygulama seviyesinde basit limit mekanizmaları kullanılabilir.
5) Deploy ve test
Geliştirme tamamlanınca Wrangler ile deploy alırsınız. Ardından uç noktaları curl veya Postman ile test edin. İlk test olarak /health çağrısının 200 dönmesi beklenir. Sonra /api/profile’a token olmadan istek atarak 401 aldığınızı doğrulayın. Son adımda geçerli bir JWT ile çağrı yapıp JSON yanıtı alın. Hata durumlarında özellikle Authorization header formatı (Bearer boşluk) ve token’ın doğru issuer/audience değerleri kontrol edilmelidir.
Sık karşılaşılan hatalar ve çözüm ipuçları
“Invalid signature”: Yanlış public key, yanlış JWKS endpoint’i veya token’ın farklı bir kid ile imzalanması. JWKS’ten doğru anahtarı seçtiğinizden emin olun. “Token expired”: exp geçmiş olabilir; sistem saatini ve clock skew toleransını gözden geçirin. CORS hataları: OPTIONS isteklerine 200 dönmeyi ve gerekli Access-Control-Allow-* başlıklarını eklemeyi unutmayın.
Sonuç: Neyi kazandınız?
Bu rehberle Cloudflare Workers üzerinde edge’de çalışan, gecikmesi düşük ve otomatik ölçeklenen bir JSON API kurmanın mantığını kurdunuz. Üstüne JWT doğrulama ekleyerek gerçek hayattaki “korumalı endpoint” ihtiyacını da çözdünüz. Buradan sonra loglama için Workers Analytics, veri katmanı için D1/KV, daha gelişmiş yetkilendirme için role-based kontrol ve rate limiting gibi adımlarla mimariyi büyütebilirsiniz.
