``

Önce temel mantık: Bağış sistemi nasıl çalışır?

Tipik bir bağış akışı; bağışçı, form, ödeme sağlayıcısı, işlem kaydı ve raporlama katmanlarından oluşur. Kullanıcı formu doldurduğunda sistem ödeme sağlayıcısına bir istek gönderir. Başarılı işlem sonrasında bağış kaydedilir, makbuz oluşturulur ve gerekiyorsa bağışçıya otomatik e-posta gönderilir.

Bir kampanyanın net geliri basitçe şöyle modellenebilir:

Burada $o_{komisyon}$ ödeme sağlayıcısının oransal kesintisini, $M_{sabit}$ işlem başına sabit maliyetleri temsil eder. Dolayısıyla yalnızca yazılımın fiyatını değil, ödeme komisyonlarını ve operasyon yükünü de karşılaştırmak gerekir.

Üç sistemin karakteri

CiviCRM: Kurumsal hafıza isteyenlere

CiviCRM yalnızca ödeme almakla kalmaz; bağışçıları, üyelikleri, etkinlikleri, e-postaları ve geçmiş etkileşimleri tek profilde toplar. Drupal, Joomla veya WordPress ile çalışabilir. Özellikle aynı destekçiyle yıllar boyunca ilişki kuran kuruluşlar için güçlüdür.

Bunun karşılığında kurulum ve bakım daha zahmetlidir. Veri modeli, roller, izinler ve zamanlanmış görevler doğru yapılandırılmalıdır. Küçük bir kampanya için ağır gelebilir; fakat binlerce kişiyle çalışan bir STK için adeta dijital genel merkezdir.

GiveWP: WordPress içinde pratik çözüm

GiveWP, mevcut WordPress sitesini bağış platformuna dönüştürür. Kampanya formları, hedef göstergeleri, bağışçı panelleri ve tekrarlayan ödeme özellikleri sunar. İçerik ekibinin WordPress’e aşina olması önemli bir avantajdır.

Basit bir entegrasyon mantığı şu şekilde düşünülebilir:

add_action('give_insert_payment', function ($payment_id) {
    $amount = give_get_payment_total($payment_id);
    error_log('Yeni bağış tutarı: ' . $amount);
});

Bu örnek, yeni ödeme kaydedildiğinde bağış tutarını günlük dosyasına yazar. Gerçek projede aynı kanca CRM bildirimi göndermek veya özel bir teşekkür süreci başlatmak için kullanılabilir. Ancak ücretli eklentiler, ödeme ağ geçitleri ve WordPress güvenliği toplam maliyete eklenmelidir.

Open Collective: Şeffaflık varsayılan ayar

Open Collective özellikle açık kaynak projeleri, yerel topluluklar ve gayriresmî gruplar için dikkat çekicidir. Gelirler ve giderler herkese açık gösterilebilir. Bir mali sponsor kullanıldığında topluluk, ayrı bir tüzel kişilik kurmadan para kabul etme ve harcama olanağı bulabilir.

Platformun en güçlü tarafı şeffaflıktır; ancak klasik CRM özellikleri veya tamamen özelleştirilebilir bağış deneyimi bekleyen kuruluşlar için sınırlı kalabilir.

Hangisini seçmeli?

Karar verirken bağış hacmi, ekip kapasitesi, veri gizliliği ve raporlama gereksinimleri birlikte değerlendirilmelidir. Kısacası CiviCRM ilişkiyi, GiveWP dönüşümü, Open Collective ise güveni ve şeffaflığı merkeze koyar. En iyi sistem en fazla özelliğe sahip olan değil, kuruluşunuzun günlük iş akışına en az sürtünmeyle uyum sağlayandır.

``

Üç platform, üç yaklaşım

Decidim, Barselona çıkışlı kapsamlı bir katılımcı demokrasi altyapısıdır. Teklif oluşturma, destek toplama, toplantı düzenleme, anket, bütçeleme ve sonuç takibi gibi süreçleri modüler biçimde sunar. Bir dilekçe sistemi kurmanın yanında tüm karar alma döngüsünü yönetmek isteyen kurumlara uygundur.

CONSUL DEMOCRACY, vatandaş önerileri, tartışmalar, oylamalar ve katılımcı bütçeleme üzerine yoğunlaşır. Teklif belirli bir destek eşiğine ulaştığında değerlendirme ya da oylama aşamasına geçirilebilir. Bu nedenle klasik “öneri ver, imza topla, gündeme taşı” modeliyle oldukça uyumludur.

FixMyStreet ise doğrudan bir dilekçe platformu değildir. Vatandaşların harita üzerinde çukur, kırık sokak lambası veya kaçak döküm gibi yerel sorunları bildirmesini sağlar. Bildirim, konuma göre sorumlu kuruma yönlendirilir ve çözüm durumu kamuya açık şekilde izlenebilir.

İmza sistemi nasıl düşünülmeli?

Basit modelde her dilekçenin bir destek sayısı ve hedefi bulunur. İlerleme oranı şöyle hesaplanabilir:

Burada $S$ doğrulanmış destek sayısını, $H$ hedeflenen desteği, $P$ ise yüzde ilerlemeyi ifade eder. Örneğin 2.000 destek hedefleyen bir öneri 1.250 doğrulanmış imzaya ulaştığında ilerleme oranı yüzde 62,5 olur.

Fakat yalnızca sayaç tutmak yeterli değildir. Aynı kişinin tekrar imza atması engellenmeli, e-posta veya kimlik doğrulaması yapılmalı ve kişisel veriler gereksiz yere yayımlanmamalıdır. İdeal süreç şu durum makinesini izleyebilir:

Taslak → Moderasyon → Yayında → Eşik Aşıldı → Kurumsal İnceleme → Sonuçlandı

Aşağıdaki basitleştirilmiş Python fonksiyonu, doğrulanmış ve benzersiz destekleri sayar:

def petition_progress(signatures, target):
    # Doğrulanmış kullanıcı kimliklerini kümeye alarak tekrarları eler.
    verified_users = {
        item["user_id"]
        for item in signatures
        if item["verified"] is True
    }

    support_count = len(verified_users)
    percentage = min((support_count / target) * 100, 100)

    return {
        "support_count": support_count,
        "percentage": round(percentage, 2),
        "threshold_reached": support_count >= target
    }

Gerçek sistemde user_id değerleri herkese açık gösterilmemeli; mümkünse tek yönlü özetler, yetkilendirme katmanları ve kayıt saklama politikaları kullanılmalıdır. Ayrıca kötüye kullanım önleme mekanizması erişilebilirliği bozmamalıdır: aşırı CAPTCHA kullanımı gerçek vatandaşları da kaçırabilir.

Hangisini seçmelisiniz?

Seçimde yalnızca özellik listesini değil; kurulum ekibinin Ruby/Rails deneyimini, barındırma bütçesini, moderasyon kapasitesini, çok dillilik ihtiyacını ve kurum içi süreçleri de değerlendirmek gerekir. En parlak arayüz bile arka tarafta dilekçeyi yanıtlayacak bir iş akışı yoksa dijital bir öneri kutusuna dönüşür.

Sonuç olarak Decidim geniş kapsamlı bir demokrasi laboratuvarı, CONSUL DEMOCRACY yapılandırılmış bir öneri ve oylama motoru, FixMyStreet ise konum tabanlı belediye sorunları için uzmanlaşmış bir araçtır. Başarılı seçim, “Hangisi daha güçlü?” sorusundan önce “Vatandaş hangi sürece katılacak?” sorusunu yanıtlamakla başlar.

``

Oylamanın teorik temeli

Basit çoğunluk oylamasında aday $i$ için kullanılan oy sayısını $v_i$ ile gösterirsek kazanan şöyle bulunur:

Ancak gerçek dünyadaki her karar “tek aday seç” biçiminde değildir. Seçmenler adayları sıralayabilir, birden fazla seçeneği destekleyebilir veya bütçe önerilerine oy verebilir. Ayrıca sistemin dört temel beklentiyi dengelemesi gerekir:

• Gizlilik: Bir oyun kime ait olduğu açıklanmamalıdır.
• Bütünlük: Oylar değiştirilememeli veya silinememelidir.
• Doğrulanabilirlik: Seçmen, oyunun sayıma katıldığını kontrol edebilmelidir.
• Uygunluk: Yalnızca yetkili kişiler ve izin verilen sayıda oy kullanabilmelidir.

Bu özellikler bazen çatışır. Kimlik doğrulamasını güçlendirmek gizlilik riskini artırabilir; tamamen anonim katılım ise mükerrer oyları engellemeyi zorlaştırabilir.

Üç platform, üç farklı karakter

Helios Voting: Matematik sandık başında

Helios, oyları açık anahtarlı şifreleme ile korur ve seçim sonucunun doğrulanabilmesi için kriptografik kanıtlar üretir. Homomorfik şifrelemenin sadeleştirilmiş fikri şudur:

Yani sistem, tek tek oyların içeriğini açmadan şifreli oyları birleştirip toplamı elde edebilir. Seçmen genellikle oyuna karşılık gelen bir takip değeri alır ve bu değerin yayımlanan sandık kayıtlarında bulunup bulunmadığını denetler. Böylece “oyum kayboldu mu?” sorusu teknik olarak kontrol edilebilir.

Bununla birlikte uçtan uca doğrulanabilirlik, seçmenin cihazında zararlı yazılım bulunmadığını otomatik olarak garanti etmez. Resmî ve yüksek riskli seçimlerde bağımsız güvenlik incelemesi şarttır.

Decidim: Oylamadan daha büyük bir sahne

Ruby on Rails tabanlı açık kaynak Decidim, yalnızca sandık kurmaz; karar alma sürecini baştan sona modellemeye çalışır. Katılımcılar öneri oluşturabilir, tartışabilir, toplantılara katılabilir ve bütçe projelerini destekleyebilir.

Bu nedenle Decidim’i “seçim uygulaması” yerine katılım altyapısı olarak düşünmek daha doğrudur. Bir belediyenin park önerilerini toplaması, projeleri tartışmaya açması ve ardından bütçe oylaması yapması için uygundur. Süreç şeffaflığı güçlüdür; fakat gizli oy gerektiren kritik seçimlerde kullanılacak özel bileşenler ayrıca incelenmelidir.

CIVS: Tercih sıralarının gücü

CIVS, seçmenlerin adayları sıralamasına dayanır. Condorcet yaklaşımında bir aday, diğer her adayı ikili karşılaştırmada yeniyorsa kazanan kabul edilir. $P(a,b)$, $a$ adayını $b$ adayına tercih edenlerin sayısı olsun:

Bu yöntem, yalnızca birinci tercihleri saymak yerine seçmenlerin genel eğilimini yakalar. Ancak döngüler oluşabilir: A, B’yi; B, C’yi; C de A’yı yenebilir. CIVS bu durumları çözmek için belirli Condorcet tamamlayıcı yöntemlerinden yararlanır.

Aşağıdaki Python kodu, iki aday arasındaki basit ikili üstünlüğü hesaplar:

def pairwise_winner(rankings, a, b):
    scores = {a: 0, b: 0}

    for ranking in rankings:
        if ranking.index(a) < ranking.index(b):
            scores[a] += 1
        else:
            scores[b] += 1

    if scores[a] == scores[b]:
        return 'berabere'
    return max(scores, key=scores.get)

Fonksiyon, her sıralamada hangi adayın daha yukarıda bulunduğunu kontrol eder. Gerçek bir Condorcet sistemi, bu işlemi bütün aday çiftleri için yaparak bir karşılaştırma matrisi oluşturur.

Hangisini seçmeli?

Kriptografik doğrulanabilirlik önceliğinizse Helios, kapsamlı katılımcı süreçler tasarlıyorsanız Decidim, seçenekleri adil biçimde sıralamak istiyorsanız CIVS güçlü adaylardır. Son karar; tehdit modeline, seçmen kitlesine, kimlik doğrulama ihtiyacına ve kullanılan seçim yönteminin anlaşılabilirliğine dayanmalıdır. Unutmayın: İyi bir dijital sandık yalnızca doğru sonucu üretmez, sonucun neden güvenilir olduğunu da gösterebilir.

``

Temel veri modeli

Sistemin merkezinde turnuva, katılımcı, karşılaşma ve puan durumu kaydı bulunur. Katılımcı bir takım olabileceği gibi tekil bir sporcu da olabilir. Bu nedenle veri modelinde team yerine daha genel olan participant adını kullanmak sistemi farklı spor dallarına uyarlamayı kolaylaştırır.

Puan tablosunu kalıcı olarak saklamak yerine maç sonuçlarından yeniden hesaplamak çoğu zaman daha güvenlidir. Böylece bir skor düzeltildiğinde eski ve yeni değerlerin birbirine karışması önlenir. Performans gerekiyorsa hesaplanan tablo önbelleğe alınabilir.

Puan hesabının matematiği

Klasik futbol sisteminde galibiyet 3, beraberlik 1 ve mağlubiyet 0 puandır. Bir katılımcının toplam puanı şu şekilde ifade edilir:

Burada $G$ galibiyet, $B$ beraberlik, $M$ ise mağlubiyet sayısıdır. Genel averaj da

formülüyle hesaplanır. Ancak masa tenisi, badminton veya e-spor ligleri set oranı, harita farkı ya da doğrudan ikili averaj kullanabilir. Bu yüzden puan kurallarını kodun içine sabitlemek yerine turnuva ayarlarında tanımlamak iyi bir fikirdir.

Hesaplama motoru

Aşağıdaki TypeScript fonksiyonu, tamamlanmış maçlardan temel puan tablosu üretir. Fonksiyon saf tutulduğu için aynı girdi her zaman aynı çıktıyı verir; test etmek de oldukça kolaydır.

type Match = {
  homeId: string;
  awayId: string;
  homeScore: number;
  awayScore: number;
  status: "finished" | "scheduled";
};

type Row = {
  id: string;
  played: number;
  won: number;
  draw: number;
  lost: number;
  scored: number;
  conceded: number;
  points: number;
};

function calculateTable(ids: string[], matches: Match[]): Row[] {
  const rows = new Map(ids.map(id => [id, {
    id, played: 0, won: 0, draw: 0, lost: 0,
    scored: 0, conceded: 0, points: 0
  }]));

  for (const match of matches.filter(m => m.status === "finished")) {
    const home = rows.get(match.homeId)!;
    const away = rows.get(match.awayId)!;

    home.played++; away.played++;
    home.scored += match.homeScore;
    home.conceded += match.awayScore;
    away.scored += match.awayScore;
    away.conceded += match.homeScore;

    if (match.homeScore === match.awayScore) {
      home.draw++; away.draw++;
      home.points++; away.points++;
    } else {
      const winner = match.homeScore > match.awayScore ? home : away;
      const loser = winner === home ? away : home;
      winner.won++; winner.points += 3;
      loser.lost++;
    }
  }

  return [...rows.values()].sort((a, b) =>
    b.points - a.points ||
    (b.scored - b.conceded) - (a.scored - a.conceded) ||
    b.scored - a.scored
  );
}

Sıralama zinciri burada puan, averaj ve atılan skor biçimindedir. İkili averaj gerekiyorsa eşit puanlı katılımcılar belirlenmeli, yalnızca kendi aralarındaki maçlardan geçici bir mini tablo oluşturulmalıdır.

Fikstür ve operasyonel ayrıntılar

Tek devreli ligde $n$ katılımcı için toplam maç sayısı

olur. Çift devreli ligde bu değer ikiyle çarpılır. Round-robin fikstür için kullanılan çember yöntemi, katılımcıları her tur döndürerek herkesin birbiriyle karşılaşmasını sağlar. Katılımcı sayısı tekse hayali bir BYE eklenir ve onunla eşleşen taraf haftayı maç yapmadan geçirir.

Gerçek dünyada maç erteleme, hükmen sonuç, katılımcı çekilmesi ve yönetici düzeltmeleri unutulmamalıdır. Her skor değişikliğini kullanıcı, zaman ve eski değer bilgisiyle bir denetim günlüğüne kaydetmek tartışmaları azaltır. Sonuç girişini yetkilendirme, eşzamanlı güncellemelerde transaction kullanma ve hesaplama motorunu bolca birim testiyle sınama da sistemin görünmeyen savunma hattıdır. Böylece puan tablosu yalnızca şık değil, son düdüğe kadar güvenilir olur.

Bir topluluk platformu kurmak, yalnızca kullanıcıların kayıt olabileceği bir sayfa hazırlamak değildir. Profil yönetimi, içerik üretimi, bildirimler, moderasyon, yetkilendirme ve kullanıcıların geri dönmesini sağlayan sosyal mekanikler birlikte düşünülmelidir. HumHub, BuddyPress ve Discourse bu problemi farklı açılardan çözer: biri sosyal ağ, biri WordPress eklentisi, diğeri ise modern forum yaklaşımını benimser.

``

Önce topluluk sisteminin mantığı

Bir üyelik sisteminin merkezinde kimlik, yetki ve etkileşim bulunur. Kimlik katmanı kullanıcının kim olduğunu; yetkilendirme katmanı hangi işlemleri yapabileceğini; etkileşim katmanı ise diğer üyelerle nasıl iletişim kuracağını belirler.

Basit bir topluluk veri modeli şöyle düşünülebilir:

Kullanıcı → Profil → Rol
Kullanıcı → İçerik → Yorum
Kullanıcı → Grup → Üyelik
İçerik → Bildirim → Kullanıcı

Topluluk sağlığını ölçmek için yalnızca kayıtlı kullanıcı sayısına bakmak yanıltıcıdır. Daha anlamlı bir ölçü, aktif kullanıcı oranıdır:

Örneğin 10.000 üyenin yalnızca 200’ü günlük olarak geri dönüyorsa aktiflik oranı yüzde 2’dir. Dolayısıyla yazılım seçerken özellik listesinden çok, hedeflenen etkileşim biçimine odaklanmak gerekir.

Üç platformun karakteri

HumHub

HumHub, Facebook benzeri akışların ve çalışma alanlarının önemli olduğu projelerde öne çıkar. Kullanıcılar profil oluşturabilir, alanlara katılabilir, gönderi paylaşabilir ve birbirlerini takip edebilir. Üniversite kulübü, şirket içi ağ veya kapalı meslek topluluğu için doğal bir seçimdir.

Modüler yapısı sayesinde takvim, görev ve dosya paylaşımı gibi yetenekler eklenebilir. Ancak tema ve modül ekosistemi WordPress kadar geniş değildir. Sunucu yönetimi konusunda temel Linux, PHP ve veritabanı bilgisi gerekir.

BuddyPress

BuddyPress bağımsız bir uygulama değil, WordPress’i topluluk sistemine dönüştüren bir eklentidir. Mevcut sitenizde blog, kurs, mağaza veya üyelik altyapısı varsa oldukça pratiktir. WooCommerce ve LMS eklentileriyle beraber kullanıldığında ücretli topluluklar kurulabilir.

WordPress kancaları üzerinden davranış eklemek mümkündür:

add_action('bp_init', function () {
    // BuddyPress yüklendikten sonra özel topluluk işlemlerini başlatır.
    if (is_user_logged_in()) {
        update_user_meta(get_current_user_id(), 'son_topluluk_girisi', time());
    }
});

Bu kod, giriş yapmış üyenin son topluluk ziyaretini kaydeder. Böylece geri dönüş oranı veya pasif üyeler analiz edilebilir. Bununla birlikte çok sayıda eklenti kullanmak performans, güvenlik ve uyumluluk sorunları doğurabilir.

Discourse

Discourse, klasik forumları daha akıcı hale getirir. Güven seviyeleri, güçlü moderasyon araçları, e-posta ile yanıt, rozetler ve gerçek zamanlı bildirimler hazır gelir. Teknik destek, açık kaynak proje veya soru-cevap odaklı topluluklar için başarılıdır.

Platformun güven sistemi, olumlu davranış sergileyen kullanıcılara zamanla daha fazla yetki verir. Bu yaklaşım moderasyon yükünü topluluğa dağıtır. Docker tabanlı önerilen kurulum güvenilir olsa da düşük kaynaklı paylaşımlı hosting paketlerine pek uygun değildir.

Hangisini seçmelisiniz?

Karar verirken toplam maliyeti $M = K + B + E$ biçiminde değerlendirebilirsiniz. Burada $K$ kurulum, $B$ bakım, $E$ ise eklenti ve entegrasyon gideridir. Yazılımların açık kaynak olması, işletmenin tamamen ücretsiz olacağı anlamına gelmez.

Özetle sosyal akış ve gruplar için HumHub, WordPress ekosistemi için BuddyPress, uzun ömürlü tartışmalar için Discourse daha uygundur. En iyi platform, en çok özelliğe sahip olan değil; üyelerin neden geri geleceği sorusuna en net cevabı verendir.

Online judge nasıl çalışır?

Bir değerlendirme sisteminin temel girdileri kaynak kod, programlama dili ve problem kimliğidir. Sistem önce kodu derler, ardından her test için programı çalıştırır. En basit toplam değerlendirme süresi şöyle düşünülebilir:

Programın herhangi bir testte süre sınırını aşması TLE, fazla bellek kullanması MLE, hatalı çıktı üretmesi ise WA sonucuna yol açar. Doğru sonuç yalnızca çıktının doğru olması değildir; programın belirlenen kaynak sınırları içinde çalışması da gerekir.

Gönderilen kod güvenilir kabul edilmez. Sonsuz döngüye girebilir, süreç oluşturmaya çalışabilir veya dosya sistemine erişmek isteyebilir. Bu nedenle judge sunucuları Linux kullanıcıları, cgroups, chroot, container veya benzeri izolasyon mekanizmalarından yararlanır. Kısacası değerlendirme sunucusu, yarışmacının koduna “Seni çalıştırırım ama evin anahtarını vermem” der.

Üç platformun karşılaştırması

DOMjudge: ICPC ruhunun temsilcisi

DOMjudge, takım yarışmaları ve klasik ICPC kuralları için oldukça uygundur. Yanlış gönderimler ceza süresine eklenir; problem çözüldüğünde süre hesabı kesinleşir. Basitleştirilmiş ceza modeli şöyledir:

Burada $T_{kabul}$ kabul dakikası, $W$ ise kabulden önceki yanlış gönderim sayısıdır. DOMjudge; yarışma yönetimi, canlı sıralama, hakem işlemleri ve ayrı judgehost makineleriyle ölçeklendirme konusunda güçlüdür. Üniversite kulübünde gerçekçi bir ICPC provası düzenlemek istiyorsanız genellikle ilk adaydır.

DMOJ: Esnek ve geliştirici dostu

DMOJ, sürekli açık problem arşivleri ve eğitim platformları için öne çıkar. Çok sayıda dili destekler; özel checker, interaktif problem ve kısmi puanlama gibi özellikler sunar. Django tabanlı web uygulaması ile değerlendirme düğümleri birbirinden ayrılabilir.

Bir problemin basit yapılandırması kavramsal olarak şöyle görünebilir:

archive: data.zip
time: 2
memory: 256
test_cases:
  - points: 20
    input: sample.in
    output: sample.out
  - points: 80
    batched:
      - input: secret.in
        output: secret.out

Bu yapı süreyi, bellek sınırını ve testlerin puan ağırlığını tanımlar. Gerçek sözdizimi sürüme ve problem paketine göre değişebilse de temel fikir aynıdır: değerlendirme davranışı kod yerine yapılandırmayla açıklanır.

CMS: Olimpiyat seviyesinde kontrol

Contest Management System, özellikle IOI biçimindeki yarışmalara yöneliktir. Alt görevler, geri bildirim düzeyleri, token sistemi ve ayrıntılı puanlama senaryolarında çok başarılıdır. Örneğin çözüm ilk alt görevden 20, ikinci alt görevden 30 puan alabilir; en zor grup başarısız olsa bile toplam puan korunur.

CMS güçlüdür ancak kurulumu ve işletimi diğer seçeneklere göre daha fazla sistem yönetimi bilgisi ister. Servislerin dağıtılması, worker makinelerinin hazırlanması ve yarışma verilerinin doğru modellenmesi dikkat gerektirir.

Hangisini seçmeli?

Tek günlük ICPC benzeri bir etkinlik için DOMjudge, okul veya topluluk tabanlı sürekli bir soru platformu için DMOJ, ulusal olimpiyat düzeyinde alt görevli yarışmalar için CMS daha doğal seçimdir. Platformdan bağımsız olarak yedekleme, HTTPS, kaynak izolasyonu ve yarışma öncesi yük testi ihmal edilmemelidir. Çünkü en zor algoritma sorusu bile çözülebilir; yarışma ortasında çöken judge sunucusu ise herkese aynı anda sistem tasarımı dersi verir.

Önce temel: OpenAPI nedir?

OpenAPI, REST tabanlı bir API’nin insanlar ve makineler tarafından okunabilen sözleşmesidir. Endpoint yolları, HTTP metotları, parametreler, veri modelleri, kimlik doğrulama yöntemleri ve olası yanıtlar YAML veya JSON biçiminde tanımlanır.

Bir API sözleşmesini kabaca şu fonksiyonla düşünebiliriz:

Burada $P$ yolları, $R$ istekleri, $M$ veri modellerini, $A$ kimlik doğrulamayı ve $E$ hata yanıtlarını temsil eder. Sözleşme ne kadar eksiksizse istemci üretimi, test otomasyonu ve geliştirici deneyimi o kadar başarılı olur.

Swagger UI ve Redoc bu sözleşmeyi görselleştirir. Docusaurus ise rehberler, eğitimler, sürüm notları ve kavramsal açıklamalar için genel bir dokümantasyon sitesi sunar.

Araçların karşılaştırması

Kısacası Swagger UI laboratuvar, Redoc düzenli bir ansiklopedi, Docusaurus ise bütün kampüstür.

Küçük bir OpenAPI sözleşmesi

Aşağıdaki dosya, kullanıcı bilgisini kimliğe göre döndüren bir endpoint tanımlar:

openapi: 3.0.3
info:
  title: Kullanıcı API
  version: 1.0.0
paths:
  /users/{id}:
    get:
      summary: Kimliğe göre kullanıcı getirir
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Kullanıcı bulundu
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: Kullanıcı bulunamadı
components:
  schemas:
    User:
      type: object
      required: [id, name]
      properties:
        id:
          type: integer
        name:
          type: string

Bu tanım tek bir doğruluk kaynağıdır. Aynı dosya arayüz oluşturmak, sözleşme testi yapmak veya istemci SDK’sı üretmek için kullanılabilir.

Swagger UI ve Redoc’u çalıştırmak

En hızlı yöntem Docker kullanmaktır:

# Etkileşimli Swagger UI

docker run --rm -p 8080:8080 \
  -e SWAGGER_JSON=/spec/openapi.yaml \
  -v "$PWD:/spec" swaggerapi/swagger-ui

# Okuma odaklı Redoc

docker run --rm -p 8081:80 \
  -e SPEC_URL=openapi.yaml redocly/redoc

İlk komut API’yi localhost:8080 üzerinde deneyebilmenizi sağlar. İkinci komut aynı sözleşmeyi daha sade ve referans odaklı bir görünümle sunar. Gerçek projede dosyayı Redoc sunucusunun erişebileceği dizine kopyalamak veya bir URL üzerinden yayımlamak gerekir.

Docusaurus ile merkezi portal

Docusaurus projesinde kavramsal rehberleri Markdown ile tutabilir, API referansına menüden bağlantı verebilirsiniz:

// docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      items: [
        { to: '/docs/intro', label: 'Rehberler' },
        { href: '/api/redoc.html', label: 'API Referansı' },
        { href: '/swagger/', label: 'API’yi Dene' }
      ]
    }
  }
};

Bu yapı kullanıcıya üç katman sunar: “Neden kullanmalıyım?” sorusunu rehberler, “Hangi alanlar var?” sorusunu Redoc, “Bu istek gerçekten çalışıyor mu?” sorusunu Swagger UI cevaplar.

Sürdürülebilir iş akışı

OpenAPI dosyasını uygulama koduyla aynı depoda saklayın. CI sürecinde sözdizimini doğrulayın, kırıcı değişiklikleri karşılaştırın ve başarılı derlemeden sonra üç aracı da yayımlayın. Sürüm numarasını URL’ye eklemek, eski istemcilerin dokümantasyona erişmesini kolaylaştırır.

Ayrıca örneklerde gerçek erişim anahtarları kullanmayın. Swagger UI üzerindeki yetkilendirme alanlarını yalnızca güvenli test ortamlarına bağlayın. Böylece güzel görünen değil; güncel, test edilebilir ve güvenilir bir API dokümantasyon sistemi elde edersiniz.

``

API testi aslında neyi doğrular?

Bir istemci API’ye HTTP isteği gönderir; sunucu ise durum kodu, başlıklar ve gövde içeren bir yanıt üretir. Test aracının temel görevi bu alışverişi görünür ve tekrar edilebilir hâle getirmektir.

Örneğin bir kullanıcı endpoint’i için yalnızca 200 OK almak yeterli değildir. Yanıt gövdesindeki id alanının bulunması, içerik türünün JSON olması ve sürenin belirlenen sınırı aşmaması da kontrol edilmelidir.

Performansı basitçe şöyle değerlendirebiliriz:

Bir test 400 ms sürüyorsa bunun tamamı sunucunun işlem süresi değildir. Ağ gecikmesi ve yanıt boyutu da sonucu etkiler. Çoklu isteklerde ortalama süre ise

formülüyle hesaplanabilir. Bu nedenle tek bir hızlı yanıt görüp zafer dansına başlamak yerine testi birkaç kez çalıştırmak daha sağlıklıdır.

Üç aracın karakteri

Hoppscotch: Tarayıcıyı aç ve isteği gönder

Hoppscotch, kurulumla uğraşmadan REST, GraphQL ve WebSocket istekleri denemek isteyenler için idealdir. Arayüzü hafiftir; URL’yi, metodu ve gerekli başlıkları girerek saniyeler içinde sonuç alabilirsiniz. Özellikle eğitimlerde, hata ayıklamada ve geçici kontrollerde parıldar.

Ancak hassas token’larla çalışırken ekip politikalarını ve verinin nerede saklandığını incelemek gerekir. Tarayıcı kolaylığı, güvenlik değerlendirmesini ortadan kaldırmaz.

Bruno: Koleksiyonlar da kod gibi yaşasın

Bruno, koleksiyonları düz metin dosyalarında saklayarak Git üzerinden sürümlemeyi kolaylaştırır. Böylece API değişiklikleri pull request içinde görülebilir; “Bu header’ı kim değiştirdi?” sorusu polisiye romana dönüşmez.

Örnek bir Bruno isteği şöyle görünebilir:

meta {
  name: Kullanıcı Getir
  type: http
  seq: 1
}

get {
  url: {{baseUrl}}/users/42
  body: none
  auth: bearer
}

assert {
  res.status: eq 200
  res.body.id: eq 42
}

Bu dosya isteğin adresini tanımlar ve yanıtın durum koduyla kullanıcı kimliğini doğrular. CLI desteği sayesinde aynı koleksiyon CI/CD hattında da çalıştırılabilir.

Insomnia: Düzenli ve kapsamlı çalışma masası

Insomnia; ortam değişkenleri, kimlik doğrulama yöntemleri, GraphQL desteği ve koleksiyon organizasyonuyla kapsamlı projelerde rahat bir deneyim sunar. Çok sayıda servisi olan ekipler için klasörlü yapı ve yeniden kullanılabilir değişkenler önemlidir.

Örneğin geliştirme ve üretim adreslerini ayrı ayrı yazmak yerine şu mantık kullanılabilir:

{
  "base_url": "https://api.example.com",
  "token": "{{ secret_token }}"
}

Böylece isteklerde `` kullanılır ve ortam değiştirirken her endpoint’i elle düzenlemek gerekmez. Token değerlerini repoya eklememek ise temel güvenlik kuralıdır.

Hangisini seçmelisiniz?

Hızlı, kurulumsuz denemeler için Hoppscotch; koleksiyonları Git ile yönetmek ve testleri pipeline’a taşımak için Bruno; kapsamlı masaüstü deneyimi ve düzenli proje yönetimi için Insomnia öne çıkar. En iyi araç, en fazla düğmeye sahip olan değil, ekibinizin testleri düzenli çalıştırmasını sağlayandır. Küçük bir örnek API’yi üçünde de deneyin; ardından hız, paylaşım, güvenlik ve otomasyon ihtiyaçlarınıza göre karar verin.

Yer imi sistemi aslında ne yapar?

İyi bir bookmark sistemi yalnızca URL depolamaz. Bir bağlantıyı; başlık, açıklama, etiket, eklenme tarihi ve arşivlenmiş içerikle birlikte saklar. Teorik olarak her kaydı şu kümeyle gösterebiliriz:

Burada $u$ adresi, $t$ başlığı, $d$ açıklamayı, $E$ etiketler kümesini, $z$ eklenme zamanını ve $a$ arşiv kopyasını temsil eder. Etiketleme sayesinde arama alanı küçülür. Toplam $N$ bağlantının yalnızca belirli bir etikete ait $k$ tanesini incelemek, zihinsel yükü kabaca $N$ öğeden $k$ öğeye indirir.

Örneğin python, veritabanı ve okunacak etiketlerinin kesişimi şöyle düşünülebilir:

Bu yaklaşım klasörlerden daha esnektir; çünkü aynı bağlantı birden fazla bağlama ait olabilir.

Üç aracın karakteri

Linkwarden

Linkwarden, bağlantı çürümesine karşı en güçlü seçenektir. Bir web sayfası silinse bile ekran görüntüsü veya PDF benzeri arşivleri koruyabilir. Koleksiyon paylaşımı ve kullanıcı yönetimi sayesinde ekipler için de uygundur. Bunun bedeli daha fazla RAM, depolama ve kurulum bileşenidir.

Linkding

Linkding, “yer imimi ekleyeyim ve hemen bulayım” yaklaşımını benimser. Arayüzü dikkat dağıtmaz; etiketleme, arama, içe aktarma ve tarayıcı eklentileri günlük kullanımda oldukça yeterlidir. SQLite kullanması yedeklemeyi de kolaylaştırır: Çoğu durumda veritabanı dosyasını güvenli biçimde kopyalamak yeterlidir.

Shaarli

Shaarli, eski bir dizüstünü sunucuya dönüştürenlerin kahramanıdır. PHP çalıştırabilen mütevazı bir sunucuda yaşayabilir ve veritabanı sunucusu gerektirmez. Arayüzü rakipleri kadar modern değildir; fakat taşınabilirlik ve sadelik konusunda oldukça güçlüdür.

Docker ile Linkding kurulumu

Aşağıdaki compose.yaml, Linkding servisini başlatır ve verileri kalıcı bir klasörde tutar:

services:
  linkding:
    image: sissbruecker/linkding:latest
    container_name: linkding
    ports:
      - "9090:9090"
    volumes:
      - ./data:/etc/linkding/data
    environment:
      - LD_SUPERUSER_NAME=admin
      - LD_SUPERUSER_PASSWORD=guclu-bir-parola
    restart: unless-stopped

Dosyanın bulunduğu dizinde şu komutu çalıştır:

docker compose up -d

Ardından http://sunucu-adresi:9090 üzerinden giriş yapabilirsin. volumes bölümü, konteyner silinse bile kayıtların data klasöründe kalmasını sağlar. Gerçek kullanımda güçlü parola, HTTPS ve düzenli yedekleme şarttır; yönetim panelini doğrudan internete açmak iyi bir macera türü değildir.

Hangisini seçmelisin?

Kalıcı web arşivi ve ekip paylaşımı istiyorsan Linkwarden, hızlı ve dengeli bir kişisel sistem arıyorsan Linkding, en düşük kaynak tüketimiyle bağımsızlık hedefliyorsan Shaarli seç. En iyi araç, yüzlerce özelliği olan değil, yeni bağlantı eklemeyi erteletmeyecek kadar rahat olandır. Sistemi seçtikten sonra az sayıda tutarlı etiket belirle, tarayıcıdaki eski yer imlerini içe aktar ve otomatik yedekleme kur. Dijital çekmecen sonunda gerçekten düzenli kalabilir.

Sağlam bir yedekleme sisteminin mantığı

Yedekleme, dosyaları başka bir klasöre kopyalamaktan ibaret değildir. Güvenilir bir plan için yaygın 3-2-1 kuralı uygulanabilir:

• Verinin en az 3 kopyası bulunmalı.
• Kopyalar 2 farklı ortamda tutulmalı.
• Kopyalardan 1 tanesi uzak konumda olmalı.

Depolama ihtiyacını azaltmak için üç araç da artımlı yedekleme yaklaşımından yararlanır. İlk çalıştırmada tüm veri saklanırken sonraki çalıştırmalarda yalnızca değişiklikler gönderilir. Basitleştirilmiş depolama hesabı şöyledir:

Burada $F$ ilk tam yedeğin boyutunu, $\Delta_i$ ise her çalıştırmada değişen veri miktarını temsil eder. Tekilleştirme sayesinde aynı veri bloklarının tekrar saklanması önlenebilir. Örneğin 10 GB’lık bir dosyanın yalnızca küçük bir bölümü değiştiğinde yeniden 10 GB göndermek gerekmez.

Üç aracın karşılaştırması

Duplicati, tarayıcıdan yönetilen arayüzü sayesinde zamanlama, hedef seçimi ve geri yükleme işlemlerini kolaylaştırır. Google Drive, OneDrive ve S3 gibi hedeflere doğrudan bağlanabilmesi önemli bir avantajdır. Buna karşılık büyük yedek kümelerinde veritabanı bakımı gerekebilir.

BorgBackup, içerik tanımlı parçalama ve güçlü tekilleştirme özellikleriyle özellikle Linux sunucularında parlar. Depoların SSH üzerinden kullanılabilmesi güvenli ve hızlı bir yapı sunar. Ancak grafik arayüz bekleyen kullanıcılar için biraz fazla terminal kokabilir.

Restic ise sade komutları, tek dosyalık kurulumu ve platformlar arası desteğiyle öne çıkar. Şifreleme varsayılan tasarımın parçasıdır; yedek deposu ele geçirilse bile parola olmadan içerik okunamaz.

BorgBackup ile örnek yedekleme

Önce şifreli bir depo oluşturulur, ardından proje dizini arşivlenir:

borg init --encryption=repokey-blake2 /mnt/backup/borg-repo
borg create --stats /mnt/backup/borg-repo::proje-{now} ~/projeler

İlk komut şifreli depoyu hazırlar. İkinci komut, tarih bilgisini taşıyan yeni bir anlık görüntü oluşturur. Eski yedekleri kontrollü biçimde temizlemek için şu politika uygulanabilir:

borg prune --list /mnt/backup/borg-repo \
  --keep-daily=7 --keep-weekly=4 --keep-monthly=6

Bu komut son yedi günlük, dört haftalık ve altı aylık yedeği korur.

Restic ile uzak hedef kullanımı

Restic deposu SFTP üzerinde hazırlanabilir:

export RESTIC_REPOSITORY=sftp:user@sunucu:/yedekler/restic
restic init
restic backup ~/Belgeler ~/Fotoğraflar
restic check

backup verileri şifreleyerek gönderirken check, depo bütünlüğünü denetler. Parola otomasyon sırasında açıkça yazılmamalı; izinleri sınırlandırılmış bir parola dosyası veya güvenli sır yönetim sistemi kullanılmalıdır.

Hangisini seçmeli?

Masaüstünde kolay yönetim ve bulut bağlantıları için Duplicati, Linux sunucusunda yüksek verimlilik için BorgBackup, farklı sistemlerde sade ve güvenli kullanım için Restic güçlü adaydır. Hangi araç seçilirse seçilsin, yalnızca yedek almak yeterli değildir. Düzenli geri yükleme testi yapılmayan bir yedek, açılana kadar Schrödinger’in yedeğidir: Hem vardır hem yoktur!