GitHub'ın star history endpoint'i, stargazers kısıtlamasının ardından yıldız grafiği verisini geri getiriyor

Stargazers kısıtlamasına GitHub'ın yanıtı

Bu yılın başlarında GitHub, bir repository'nin stargazers listesinde artık herkesin sayfalama yapmasına izin vermeyi bıraktı. Yusuf Cengiz'in dev.to'daki yazısına göre liste, bir repository'nin yöneticileri ve ortak çalışmalarıyla sınırlandı; bu da listeyi veri kaynağı olarak kullanan star history araçlarını kesintiye uğrattı.

Cengiz'in yazdığına göre Eylül ayında GitHub amaca özel bir çözüm sundu: GET /repos/{owner}/{repo}/stargazers/history adresinde bir star history endpoint'i. Bu endpoint, o araçların aslında istediği aynı temel sinyali — bir repository'nin zaman içinde nasıl yıldız topladığını — sunuyor; ancak bunu bireysel stargazer'lar listesi olarak değil, önceden toplanmış haftalık kovalar halinde veriyor.

Endpoint ne döndürüyor

Yanıt, en yenisi başta olacak şekilde hafta nesnelerinden oluşan bir dizi. Her kayıtta haftayı tanımlayan bir Unix timestamp, o hafta için bir total değeri ve Pazar gününden başlayan yedi günlük sayımları içeren bir days dizisi var. Yazıdaki örnek payload, 19 yıldızlık bir haftayı gösteriyor: 12'si Pazartesi, 7'si Salı günü.

Yazıda belgelenen diğer ayrıntılar:

• Herhangi bir public repository için kimlik doğrulaması olmadan çalışıyor.

• Her sayfada en fazla 30 hafta bulunuyor ve bir çağırıcı en fazla 100 sayfa isteyebiliyor. Cengiz, gerekli sayfa sayısını repository'nin yaşından türetiyor ve sayfaları paralel olarak çekiyor.

• İsim değişiklikleri ele alınıyor: facebook/react geçmişini istediğinizde, repository'nin önceki adı olan react/react altında kaydedilmiş geçmiş dönüyor.

• Doğruluğu kontrol etmek için Cengiz haftalık toplamları toplayıp vercel/next.js ve torvalds/linux dahil yedi repository'deki canlı yıldız sayılarıyla karşılaştırmış. Toplamlar her durumda tam olarak eşleştiğini bildiriyor.

README yıldız grafiklerini yeniden inşa etmek

Cengiz, endpoint'in üzerine GitHub README'lerine gömülmek üzere bir grafik üreteci kurmuş; starhistory.link adresinde barındırılıyor ve kaynak kodu GitHub hesabında YusufCeng1z/star-history olarak yayınlanıyor.

Script'ler bir README içinde çalışmadığı için grafiğin bir görsel olması gerekiyor. Üreteç, bir Svelte bileşenini sunucu tarafında bir SVG yanıtına dönüştürüyor, ardından düz CSS keyframe'lerle canlandırıyor: çizgi stroke-dashoffset kullanılarak çiziliyor, dolgu belirginleşiyor ve pathLength değerinin 1000'e ayarlanması dash davranışını path'in gerçek uzunluğundan bağımsız olarak tutarlı kılıyor. Blok karakterlerden oluşturulmuş bir ASCII varyantı ve eğri üzerinde süzülen küçük bir roketin bulunduğu bir tema dahil sekiz görsel tema mevcut.

Open Graph kartları SVG yerine PNG'ye ihtiyaç duyuyor ve Cengiz, resvg'nin CSS değişkenlerini de animasyonu da desteklemediğini belirtiyor. Bu nedenle sosyal görsel, sabit renklerle ayrı ve statik bir SVG; resvg ile PNG'ye dönüştürülüyor ve fontlar npm'den paketleniyor. Grafik çıktısı yaklaşık 120 noktaya seyreltiliyor ve bir saat boyunca önbelleğe alınıyor.

Yerini aldığı geçici çözüm

Resmi endpoint'i bulmadan önce Cengiz, public GH Archive veri setiyle denemeler yapmış. Bu veri yıldız olaylarını repository kimliğine değil adına göre kaydediyor; bu yüzden herhangi bir isim değişikliği eski geçmişi yetim bırakıyor. Etkisi somuttu: vuejs/core yıldızlarının yalnızca yüzde 51'ine sahip gibi görünüyordu, çünkü önceki olaylar eski adı olan vuejs/vue-next altındaydı. Cengiz, eski adları bulup repository kimliğiyle doğrulayan bir katman yazdı; resmi endpoint isim değişikliklerini yerel olarak ele aldıktan sonra ise hepsini sildi.

Neden önemli

Stargazers kısıtlamasası, maintainer'lerin zaman içindeki büyümeyi göstermek için proje README'lerine gömdüğü küçük bir araç ekosistemini sessizce bozdu. Yeni endpoint bu yeteneği, orijinal listeden tüketilmesi gerekirse daha da kolay bir arayüzle geri getiriyor: toplanmış, public repository'ler için kimlik doğrulaması gerektirmeyen ve isim değişikliklerinden haberdar bir yapı.

API tüketicileri için burada daha geniş bir ders de var. Repository adına göre anahtarlanmış veriler üzerine kurulu geçici çözümler — GH Archive gibi — bir proje taşındığında geçmişi sessizce kaybediyor; oysa repository kimliğini takip eden resmi bir endpoint bunu yapmıyor. Asıl uyarı ise şu: yukarıdaki her şey tek bir geliştiricinin yeni yayınlanmış bir endpoint hakkındaki anlatımından geliyor; sayfalama limitleri ve anonim erişim gibi ayrıntılar, production'da bunlara güvenmeden önce yeniden doğrulanmaya değer.