GitHub’ın yeni yıldız geçmişi API’si: Daha az veriyle daha iyi tasarım

Bir grafiği çizmek için binlerce kullanıcının kaydını indirmek gerçekten gerekli mi? GitHub’ın 14 Ekim 2026 tarihli mühendislik yazısı bu soruyu somut bir örnekle gündeme taşıdı: depo yıldızlarının zaman içindeki değişimini göstermek. Konu yalnızca GitHub kullananları ilgilendirmiyor. Yönetim panelleri, ziyaret istatistikleri ve satış raporları tasarlayan geliştiriciler için de aynı kararlar söz konusu.

Yeni olan ne?

GitHub’ın açıklamasına göre yeni yaklaşım, yıldız veren kişileri listelemek yerine günlük sayımları takvim haftaları halinde döndürüyor. Şirketin React deposu üzerinden verdiği karşılaştırmada, geçmişi çıkarmak için gereken istek sayısı yaklaşık 2.511’den 24’e düşüyor. Bunlar GitHub’ın kendi örneğine ait rakamlar; her depo veya başka bir uygulama için aynı hızlanmayı vaat etmiyor.

Haberdeki önemli ayrıntı, yalnızca yanıtın küçültülmemesi. Sorguya önce zaman aralığı uygulanıyor, ardından o aralıktaki kayıtlar gruplanıyor. Böylece küçük bir sonuç üretmek için tüm geçmişi tekrar tekrar işleme ihtiyacı azaltılıyor. Aynı fikir, kendi uygulamanızdaki raporlara da uyarlanabilir.

API sözleşmesini gerçekten gereken veriye göre kurmak

Resmî API belgesi yıldız geçmişinin hafta, toplam ve günlük sayılarla döndüğünü açıklıyor. Haftalar en yeniden eskiye sıralanıyor; günlük dizi pazar günüyle başlıyor. Belgede hafta ve gün sınırlarının UTC ile aynı olmasının garanti edilmediği de belirtiliyor. Bu ayrıntıyı atlayan bir grafik, doğru sayıları yanlış tarih etiketleriyle gösterebilir.

Buradan çıkarılabilecek ilk tasarım sorusu şu: kullanıcı ekranda neye karar verecek? Amaç bir kampanyanın ardından ilginin artıp artmadığını görmekse, kişi listesi genellikle grafik için gereksizdir. Ancak destek ekibinin tek bir kaydı araştırdığı ekranın ihtiyacı farklıdır. Aynı uç noktayı iki kullanım için zorlamak yerine, özet ve ayrıntı sorgularının ayrı sözleşmeleri olabilir.

Küçük yanıt ile küçük iş yükünü ayırmak

Bir raporun yalnızca on satır göstermesi, veritabanının yalnızca on satıra baktığını kanıtlamaz. Örneğin aşağıdaki sorgu bir örnek uygulama içindir; GitHub’ın gerçek şeması veya üretim sorgusu değildir. Tarih filtresinin rapor aralığını açıkça ifade etmesi amaçlanıyor.

SELECT DATE(created_at) AS gun, COUNT(*) AS adet
FROM olaylar
WHERE created_at >= :baslangic
  AND created_at < :bitis
GROUP BY DATE(created_at)
ORDER BY gun;

Bu örneği kendi sistemine taşırken ilk iş rastgele indeks eklemek olmamalı. Veri hacmi, mevcut indeksler, filtrelerin seçiciliği ve yürütme planı birlikte incelenmeli. Test ortamında dar ve geniş tarih aralıkları denenebilir; toplam süreyle birlikte okunan satır miktarı da karşılaştırılabilir. Paylaşımlı bir sunucuda aynı anda çalışan raporların etkisi ayrıca düşünülmelidir.

Grafiğin anlamını da belgelemek gerekiyor

Bir istatistik ekranının doğruluğu, sayısal değerlerin doğru olmasından ibaret değildir. Eksik gün sıfır mı demektir, yoksa veri henüz gelmedi mi? Saat dilimi değişince önceki günün sayısı değişir mi? Bir kullanıcı kaydını sildiğinde geçmiş rapor da güncellenir mi? Bunlar ekranın dipnotunda veya API sözleşmesinde yanıtlanabilecek sorulardır.

Pratik bir kontrol, aynı raporu hem tek aralıkta hem iki bitişik aralıkta hesaplamaktır. Tanımlanan istatistiğin özelliğine göre sonuçların birleşimi karşılaştırılır; sınırdaki kayıtların iki kez sayılmadığı ve atlanmadığı doğrulanır. Ardından yetki denetimi ayrı test edilir: sayım verisi göstermek, her sayımın herkese açık olması gerektiği anlamına gelmez.

Bu gelişmenin yazılım ekipleri açısından değeri, bir ürün özelliğinin veri modeline körü körüne uymak zorunda olmadığını göstermesi. Grafiğin ihtiyacı yeniden tanımlandığında hem gereksiz kişisel veri taşımak azaltılabilir hem sorgu maliyetine daha açık bir sınır konabilir. Sonuç, ölçüm ve doğru sözleşmeyle değerlendirilmelidir.