CorsAPI kullanım kılavuzu — uygulamanız ve altyapınız için

CorsAPI, ön uçunuz (veya herhangi bir HTTP istemcisi) ile üçüncü taraf HTTP API’leri arasına oturur. Tanımladığınız CORS kurallarını uygular, hedef URL’yi host ve path izin listelerine göre doğrular, API anahtarıyla kimliğinizi bağlar ve dakika başına kotaları uygular. Açık bir relay değildir: yalnızca açıkça izin verdiğiniz host ve path’lere çıkılabilir; bu güvenlik ve uyumluluk için kritiktir.

Backend ve veritabanını siz barındırırsınız. Panelde proje oluşturur, tarayıcı origin’lerini yapıştırır, upstream host’ları (isteğe bağlı jokerlerle) listeler, path önekleriyle daraltır ve API anahtarı üretirsiniz. curl, React fetch veya mobil WebView için kavram aynıdır; yalnızca tarayıcı çağrılarında doğru Origin ve CORS başlıkları gerekir.

Kayıt olduktan sonra panele girersiniz. Proje; proxy kurallarını, API anahtarlarını ve kota sayaçlarını kapsayan birimdir. Organizasyonlar isteğe bağlıdır; ekipler ve roller paylaşımı için kullanışlıdır. Tek geliştirici için başlangıçta bir proje yeter; izole anahtar ve limit için ileride ortam / üretim ayrımı yapabilirsiniz.

Her proxy isteği gönderdiğiniz API anahtarıyla bir projeye yazılır. Panelden anahtarı döndürdüğünüzde eski sır yeni istekler için hemen geçersiz olur; kesintisiz dağıtım için kısa süreli çakışma planlayın.

Girişten sonra çalışma alanında bir proje seçersiniz. Tek yerde tutarsınız: izinli tarayıcı origin’leri, upstream host kuralları, isteğe bağlı path önekleri, dakika başına hız limiti ve API anahtarları. Bir şey bozulduğunda tek seferde bir değişken değiştirin — tarayıcı CORS hatası veriyorsa önce origin’leri; proxy 400 dönüyorsa önce host/path ve URL kodlamasını kontrol edin.

Ortam başına (ör. geliştirme ve üretim) ayrı adlandırılmış anahtarlar oluşturun; birini iptal ederken diğerini düşürmeyin. Kullanım özetleri ani yükün tek anahtardan mı yoksa tek upstream’den mi geldiğini görmenize yardım eder. Anahtarları parola gibi görün: herkese açık taleplere veya paylaşılan belgelere yapıştırmayın; sızma ihtimalinde hemen döndürün.

Proje ayarları uygulamanız ile proxy arasındaki sözleşmedir: sürüm başına hangi host ve path’lerin onaylı olduğunu kısa bir iç notta tutun; sağlayıcı taban URL değiştirirken gözden geçirin.

Tarayıcılar çapraz köken XHR/fetch’te Origin başlığı gönderir. CorsAPI bu değeri projenizdeki origin listesiyle karşılaştırır. Her satır tam origin olmalı: şema + host + port, örn. http://localhost:5173 veya https://app.example.com. Sondaki eğik çizgi gerekmez; http ve https farklı origin sayılır.

Yerel geliştirmede sık sık birden fazla port kullanılır (frontend 3000, araç 5173). Kullandığınız her portu ekleyin. Vercel/Netlify önizlemeleri benzersiz alt alan adları üretir; test ederken ekleyin veya ekibiniz ortak bir önizleme adresi kullanıyorsa onu tanımlayın. Origin eksikse proxy upstream’e izin verse bile tarayıcı CORS hatası verir.

Host kuralları proxy’nin hangi DNS adlarına çağrı yapabileceğini tanımlar. Örnek: api.stripe.com, api.github.com. *.example.com gibi alt alan jokerleri tek seviyede eşleşir (api.example.com evet; a.b.example.com hayır). Mümkün olduğunca dar tutun: yalnızca entegre olduğunuz API’lere izin verin.

Host izinli değilse istek ağınızdan çıkmadan reddedilir. Bu, yanlışlıkla açık proxy davranışını ve istemci kodundaki yazım hatalarıyla beklenmedik alanlara gidişi engeller.

Bir host için path kurallarını boş bırakırsanız o host’taki tüm path’ler diğer limitler dahilinde izinlidir. /v1/ veya /repos gibi önekler tanımlarsanız yalnızca bu öneklerle başlayan URL’lere izin verilir. Büyük bir API yüzeyi varken ürününüzün birkaç rotaya ihtiyacı olduğunda kullanışlıdır.

Aynı alan adı arkasında birden fazla servis varsa host + path birleşimiyle yüzeyi bölebilirsiniz. Şüphede önce kısıtlayıcı başlayın; gerçek trafik örüntülerini gördükten sonra gevşetin.

Her projenin en az bir gizli anahtarı vardır. Her proxy isteğinde X-CorsAPI-Key: <gizli> veya Authorization: Bearer <gizli> gönderin. Backend anahtarı doğrular, proje kurallarını yükler, ardından sorgu dizesinde ilettiğiniz upstream URL’ye iletir (tam parametre adları için OpenAPI’ye bakın).

Sunucu tarafı çağrılarda anahtarı ortam değişkeninde tutun ki paketlere hiç düşmesin. Tarayıcı çağrılarında anahtar istemcide olur; bu yüzden bu projeyi kamuya açık bir yüzey gibi ele alın: host, path ve kotaları agresif sıkılaştırın ve aynı anahtarla iç yönetim API’lerine yol açmayın.

Bağlantıyı fetch’ten önce curl ile doğrulayın. YOUR_SECRET yerine paneldeki anahtarı koyun ve hedef URL’yi kodlayın. 200 ve upstream gövdesi host/path, anahtar ve ağın çalıştığını gösterir. 401 anahtar hatası veya iptal; 400 çoğunlukla kodlama veya izin listesi uyumsuzluğudur.

Operasyon runbook’larınızda curl örnekleri tutun; ön uç derlemesi olmadan sorun üretilebilsin.

SPA içinden ekibinizin o ortam için tanımladığı CorsAPI taban URL’sine (ör. uygulamanızın API’siyle aynı host veya ayrılmış bir alt alan) proxy yolu ve anahtar başlıklarıyla çağrı yapın. Tarayıcı projenizde listelenen bir origin’de çalışmalıdır. mode: 'cors' kullanın; CorsAPI Access-Control-* başlıklarını origin listenize göre üretir.

Kendi oturum çereziniz ile CorsAPI anahtarını karıştırmayın: anahtar proxy projesini tanımlar; oturum çerezi ayrıdır.

Node, Deno veya sunucusuz işleyicilerde anahtarı gizliliklerde saklayıp curl ile aynı şekilde çağırın. Zamanlanmış görevler, üçüncü taraflara yayılan webhook’lar veya upstream’in yalnızca veri merkezi IP’lerinizi görmesi gereken senaryolar için idealdir. Tek projede merkezi kota ve denetlenebilirlik korunur.

Yatay ölçekte aynı anahtarı paylaşan çok örnek vardır; dakika penceresi ortaktır. ani yük tüm tüketiciler için pencerenin tükenmesine yol açmasın diye limitleri tasarlayın.

Özel başlık gönderebilen her ürün proxy’yi kullanabilir — REST istemcileri, düşük kodlu otomasyon, zamanlanmış işler veya yerel mobil yığınlar. Aracı CorsAPI taban URL’nize yönlendirin; yayımlanan API referansındaki proxy yolunu ve parametreleri kullanın; upstream hedef URL’yi gerektiği gibi iletin; X-CorsAPI-Key veya Authorization: Bearer ile proje sırrınızı gönderin.

Masaüstü API test araçlarında (ör. Postman, Insomnia) taban URL ve anahtarı ortam veya koleksiyon değişkeninde tutun; sırları her istekte yeniden yazmayın. Aynı çağrıyı curl ile üretin; sorun araçta mı, TLS’de mi yoksa proxy kurallarında mı ayırt edin.

HTTP adımı sunan otomasyon platformlarında yöntem, URL ve başlıkları eşleştirin; örneklerdeki proxy URL’sini aynen kullanın; bazı arayüzler sorgu dizesini otomatik kodlar — çift kodlamadan kaçının. Zamanlanmış işlerde dakika kotasına uyun; çağrıları aralıklı yapın veya işi kendi tarafınızda gruplayın.

Üretim sırlarını herkese açık koleksiyonlara, paylaşılan parçacıklara veya kontrolünüzde olmayan koda gömeyin. Demolar için host kapsamı dar, limit sıkı geçici bir proje kullanın.

Başarılı proxy yanıtlarında X-RateLimit-Limit ve X-RateLimit-Remaining gibi ipuçları bulunur (tam adlar kurulumunuza göre değişebilir; canlı yanıta bakın). Bunlar projenizin dakika bütçesini yansıtır. Sert hatadan önce istemcide geri çekilmek için bunları izleyin.

Pencere dolunca HTTP 429 alabilirsiniz. Yeniden denemelerde üstel geri çekilme ve jitter kullanın; kullanıcı yalnızca ağ hatası değil ürün limitine de takıldığında arayüzde net durum gösterin.

400: bozuk proxy URL’si, doğrulama veya host/path izni yok — yapılandırma veya kodlamayı düzeltin. 401: API anahtarı eksik/geçersiz veya panel oturumu geçersiz. 429: kota aşıldı — yavaşlayın veya operatörünüz izin veriyorsa limiti artırın. 502/504: upstream veya zaman aşımı — okumalar için idempotent yeniden deneme, yazmalarda fırtına oluşturmayın.

Dağıtımınız ilişkilendirme kimliği ekliyorsa günlüklerle eşleştirin; hatalar tek upstream veya tek anahtarda mı kümeleniyor panel analitiğiyle karşılaştırın.

Siteye giriş kontrol düzlemi için httpOnly çerezde oturum saklar. Bu oturum proxy proje anahtarından ayrıdır. Çıkış panel oturumunu temizler; proje anahtarlarını açıkça döndürmediğiniz sürece döndürmez.

Otomasyon için API anahtarı ve sağlık uçlarını tercih edin; paneli taramayın.

Sürecin yanıt verip vermediğini bilmek için GET /api/health/live, veritabanı şartı için /api/health/ready, daha geniş kontrol için /api/health kullanın. Kubernetes readiness veya yük dengeleyici kontrollerine bağlayın; kötü dağıtımdan önce trafiği kesin.

Altyapı şeklinizi gizleme gereksinimi varsa ayrıntılı sağlığı kimlik doğrulamadan açmayın.

GET /api/plan/limits geçerli ücretsiz katman üst sınırlarını kimlik doğrulamadan döndürür. Dahili araçlarda limit göstermek veya dağıtım sonrası yapılandırmayı doğrulamak için kullanın.

Etkileşimli API dokümantasyonu, dağıtımınız açtığında /api/docs altında olabilir. Üretimde bu adresi kısıtlayın (ör. ağ erişimi veya kimlik doğrulama); yüzey anonim taranmasın. Entegrasyon sırasında proxy ve ilgili uçların parametre adlarını doğrulamak için yayımlanan şemayı kullanın.