API metodolojisi

Convertitive’nin sunduğu her dönüşüm, /api/v1/ altında bir JSON uç noktası olarak da mevcuttur. API, FAZ 4’ten bu yana canlıdır ve kullanıcı arayüzüyle aynı faktörleri ve formülleri sunar — bir sonuç sayfada doğruysa, API’den de doğrudur.

Uç nokta tasarımı

REST tarzı. Yol kaynağı tanımlar, sorgu dizisi parametreleri taşır. Örnekler:

• GET /api/v1/convert/unit?category=length&from=cm&to=inches&value=5
• GET /api/v1/convert/currency?from=USD&to=EUR&value=100
• GET /api/v1/convert/color?from=hex&to=rgb&value=%23FF6B35
• GET /api/v1/categories — her birim kategorisini listeler
• GET /api/v1/health/ — servis sağlığı (çalışma süresi + sürüm)

POST gövdesi yok. Tüm girdiler sorgu parametresidir. Eşdeğer, önbelleğe alınabilir, tarayıcı dostu.

Yanıt zarfı

Her başarılı yanıt aynı şekli kullanır:

{
  "ok": true,
  "data": { /* uç noktaya özgü */ },
  "meta": { /* isteğe bağlı meta veri: rateDate, factor, vb. */ }
}

Her hata yanıtı:

{
  "ok": false,
  "error": {
    "code": "INVALID_PARAM",
    "message": "İnsan tarafından okunabilir açıklama",
    "param": "from"
  }
}

Standart HTTP durum kodları: başarı için 200, girdi hataları için 400, bilinmeyen kategoriler/birimler için 404, gerçekten bir şey bozulduğunda 500. 4xx’i yeniden denenebilir olarak ele almayın.

CORS politikası

Her API uç noktasında Access-Control-Allow-Origin: *. Yerel geliştirme dahil herhangi bir kaynaktan kullanın. Her istek özel başlıklar içermeyen GET olduğundan ön kontrol gerekli değildir — basit istek kuralları geçerlidir.

Kimlik doğrulama yok

API anahtarı yok, OAuth yok, imzalı istek yok. Her uç nokta anonimdir. Üç neden:

1. Veri, kapı koymaya değecek kadar değerli değil. Birim dönüşüm faktörleri kamu malıdır. ECB tarifeleri ~20 servis tarafından kamuya açık olarak yeniden yayımlanır. Bunlar için ücret almak başkasının verisi için ücret almak olurdu.
2. Kimlik doğrulama, baskın kullanım durumu için sürtünme ekler. Bir özelliği test eden geliştirici, bir ödev karşılaştırması yazan öğrenci, bir izleyici oluşturan hobi kullanıcısı — hiçbiri önce kayıt olmak istemez.
3. Hız sınırları kötüye kullanımı önler. Cloudflare’nin varsayılanları ve her dönüşümün önemsiz hesaplama maliyeti, Convertitive’yi taramaya çalışan birinin verileri doğrudan ECB beslemesini yansıtarak daha hızlı alabileceği anlamına gelir.

Sürümleme

/api/v1/ öneki kasıtlıdır. Yanıt zarfı veya hata şekli anlamlı biçimde değiştiğinde, bir /api/v2/aynı anda çıkar; v1, v2’nin lansmanından sonra en az 12 ay desteklenir.

Hata düzeltme ve eklemeli değişiklikler (yeni uç noktalar, yanıtlarda yeni isteğe bağlı alanlar) sürüm değişikliği olmaksızın sürekli olarak yayımlanır.

API’nin kendisi yerel ayar agnostiğidir — sayılar, birim sembolleri ve ISO kodları tercüme edilmez — ancak onu belgeleyen editoryal sayfalar edilir. Yerelleştirilmiş varyantları yerel ayar başına yol önekleri altında yayımlar ve bunları merkezi bir çeviri kayıt defterinden oluşturulan hreflang açıklamalarıyla arama motorlarına sinyalleriz, böylece /es/methodology/api/’nin bir İspanyolca okuyucusu aynı JSON sözleşmesini kendi dilinde açıklanmış olarak alır.

Döviz kuru tazeliği

Döviz uç noktaları, ISR aracılığıyla bir saat önbelleğe alınmış ECB orta piyasa kurunu döndürür. Her döviz yanıtındaki meta.rateDate alanı, kurun ne zaman yayımlandığını söyler (her zaman yakın bir ECB iş günü). Yüksek hassasiyetli gerçek zamanlı çalışmalar için kurları brokerınızdan alın; diğer her şey için önbelleğimiz yeterlidir.

API’ye eklemeyeceklerimiz

• Durum bilgisi gerektiren işlemler için POST uç noktaları (durum bilgimiz yok).
• Toplu uç noktalar (tekilleri döngüye alın; yeterince hızlı).
• WebSocket / akış (veri, protokolü haklı kılacak kadar sık değişmiyor).
• API anahtarları / ücretli katmanlar (yukarıdaki “kimlik doğrulama yok” bölümüne bakın).

Algoritma ayrıntıları: uçtan uca istek yaşam döngüsü

Her API isteği, gözlemlenebilir davranışın uç noktalar arasında tekdüze olması için aynı altı aşamalı ardışık düzenden geçer. Sırasıyla aşamalar:

1. Uç yönlendirme. Cloudflare, isteği önbelleğe alınmış rota haritasıyla eşleştirir ve önbelleğe alınmış yanıtı sunar (döviz, popüler birim çiftleri) ya da kaçırma durumunu Next.js fonksiyonuna iletir. p50 önbellek isabet gecikmesi: ~25 ms; önbellek kaçırma p50: ~70 ms.
2. Yöntem & CORS ön kontrolü. GET olmayan yöntemleri 405 ile reddedin. WHATWG Fetch spesifikasyonuna göre her yanıtta Access-Control-Allow-Origin: * başlığını uygulayın.
3. Şema doğrulama. Zod tarzı şemayla sorgu parametrelerini ayrıştırın. Eksik veya hatalı biçimlendirilmiş parametreler { ok: false, error: { code: "INVALID_PARAM", param } } ile 400 döndürür.
4. Dönüşümü çözümle. Hedef dönüşümü, kullanıcı arayüzünün kullandığı kayıt defterinde ara (birimler, döviz, renk, görüntü …). Döviz için ISR önbelleğini oku; birim/renk için fonksiyon deterministik saf bir hesaplamadır.
5. Zarfı biçimlendir. Her zaman { ok: true, data, meta }. Sayılar, yerel tüketici ayrıştırması için RFC 8259 uyarınca JSON sayıları olarak serileştirilir (dize olarak değil).
6. Önbellek başlıkları. Döviz yanıtları Cache-Control: public, max-age=3600, stale-while-revalidate=86400 alır; matematik hiç değişmediğinden birim/renk yanıtları max-age=31536000, immutable alır.

Kaynaklar ve referanslar

API tasarımı RFC 9110’dan HTTP semantiğini ve RFC 9111’den HTTP önbelleğe alma kurallarını izler. CORS davranışı WHATWG Fetch spesifikasyonunu izler. Yanıt gövdeleri RFC 8259 uyarınca UTF-8 JSON kullanır. Hata zarfı gerekçesi RFC 7807’ye (Sorun Ayrıntıları) dayanır. Kanonik spesifikasyonlar için sayfanın altındaki Kaynaklar bloğuna bakın.

Varsayımlar ve sınırlamalar

• Yalnızca GET. POST/PUT/DELETE yok. Gövde gerektiren her şey farklı bir tasarım ve büyük olasılıkla kimlik doğrulama gerektirir.
• İstek gövdesi ayrıştırması yok.Tüm girdiler URL kodlamalı sorgu parametreleridir. ~2 KB’dan büyük girdiler aracı URL uzunluğu sınırlarına çarpabilir.
• Hız sınırları API anahtarı başına değil, ağ kenarında. Bir NAT’ı paylaşan yüksek hacimli istemciler aynı kotayı paylaşabilir; üretim yükleri için ilgili verileri yerel olarak yansıtın.
• SLA yok.API en iyi çaba esasında çalışır. Agresif önbelleğe alın ve 5xx’i geçici olarak ele alın.
• Yapılandırılmış WebSocket / SSE yok. Temel veriler en fazla saatlik güncelleme aldığından yoklama yeterlidir.
• Yalnızca JSON, XML / msgpack yok. Accept anlaşması uygulanmadı.
• Bazı eski yanıtlarda saat dilimi bilgisi olmayan zaman damgaları. Tüm yeni uç noktalar açık ofsetli ISO 8601 yayımlar; v1.4 öncesi alanlar konvansiyon gereği UTC’dir ancak Z soneki içermez.

Canlı belgeler: /api/.