API Referansı

Önceki ders üç depo belgesini ölçtü ve üçünde de imza payı yarıyı geçmiyordu. Deponun en kalabalık imza yığını başka bir yerde duruyor. İkinci ders arayüz referansını ikinci sürümde 2/15 ile bırakmıştı ve bunun nedeni yazarın özensizliği değildi: on beş iddianın 13’ü en hızlı değişen yüzeye asılıydı.

Bu ders o türü kendi düzeniyle ele alır. Önce referansın nasıl bölümlendiği kurulur — uç nokta, parametre, hata — sonra tek bir soru ölçülür: bu iddialar elle yazılmak zorunda mı? Yazılmazsa ne kadarı kurtulur ve geriye tam olarak ne kalır?

Referansın Üç Bölümü

Referans okunmak için değil, bakılmak için yazılır. Okur ne aradığını bilir ve tek bir hücreyi doğrulamak ister. Bu yüzden referansın düzeni anlatı değil, tablodur; ve tablo olmasının tek gerekçesi biçim tercihi değildir: tablo, her hücrenin tek bir iddia taşımasını ve eksiğinin göze çarpmasını sağlar. Tablonun üç bölümü vardır.

Uç nokta çağrının kimliğini verir: yöntem, yol ve yolun içindeki değişken parçalar. Parametre her girdinin adını, nereden alındığını, tipini, zorunluluğunu ve varsayılanını verir. Hata ise çağrının başarısız olabileceği yolları sayar: durum kodu, hata kodu ve hangi koşulda döndüğü.

# kurgu ürünün arayüz referansından bir giriş
# örnek metin, çalıştırılmamıştır

GET /olcum/{istasyon}/ozet
  bu uç nokta referansta "istasyon özeti" adıyla geçer

  istasyon   yol parametresi     dizgi    zorunlu
  aralik     sorgu parametresi   tamsayı  varsayılan 60, alt sınır 1
  bicim      sorgu parametresi   dizgi    "duz" | "tablo"

  200  ozet nesnesi döner
  404  istasyon-bulunamadi   verilen istasyon tanımlı değil
  422  aralik-gecersiz       aralık alt sınırın altında

Bu girişte yazılan hemen her şey arayüzün biçimidir: yol kalıbı, parametre adları, tipler, varsayılanlar, durum kodları. Yalnız iki şey biçim değil — uç noktanın referansta anıldığı ad ve hata kodlarının adları. İkisi de ad yüzeyindedir ve az sonra tek başlarına bir sonuca dönüşecekler.

Parametre Satırının Alanları

Bir parametre satırı altı şey söylemek zorundadır ve eksiği okurun kaynağa gitmesine yol açar: ad, konum (yolda mı, sorguda mı, gövdede mi), tip, zorunluluk, varsayılan ve sınır. Yukarıdaki girişte aralik satırı altısını da taşıyor; bicim satırı varsayılanı taşımıyor ve okur “vermezsem ne olur” sorusuyla baş başa kalıyor.

Bu altı alanın hepsi imza yüzeyindedir, dolayısıyla hepsi iki sürümde bir bayatlama riskini taşır. Ama aralarında bir ayrım vardır: ilk dördü kaynaktaki bildirimden okunabilir, varsayılan ve sınır çoğu zaman kodun gövdesinde durur ve bildirimden okunmaz. Bu ayrım üretimin ne kadarını kurtarabileceğini önceden belirler; ölçüm bunu bir bütün olarak sayacak, ama uygulamada üretimin kapsamı tam olarak buradan başlar.

Satırın taşımadığı bir şey de kasıtlıdır: neden. aralik parametresinin alt sınırının neden bir olduğu referansa yazılmaz, açıklamaya yazılır. Yazılırsa iki yerde durur, ikisi ayrı hızda bayatlar ve okur hangisinin güncel olduğunu bilemez.

Durum Kodu ve Hata Kodu

Hata bölümündeki iki sütun aynı şeyi söylemez ve karıştırılmaları pahalıdır. Durum kodu kabaca sınıflandırır: istek yanlış mıydı, kaynak yok muydu, sunucu mu çöktü. Hata kodu ise tek bir durumu adlandırır — istasyon-bulunamadi ile olcum-bulunamadi aynı durum kodunu döndürebilir ve okurun yapacağı iş bambaşkadır.

Buradan pratik bir sonuç çıkar: istemci durum koduna göre değil, hata koduna göre dallanır. Yani referansın en çok güvenilen hücresi, ölçümde ad yüzeyinde duran hücredir. Sayıca azdır — on beş iddianın ikisi — ama üzerine kod yazılan iddia odur. Bayatladığında dallanma sessizce yanlış kola girer; ne bir tip hatası verir ne bir uyarı.

Hata bölümü çoğu referansta en zayıf bölümdür ve nedeni ölçülebilir. Başarılı yol bir kez yazılır ve her çağrıda sınanır; başarısız yollar ise yazılmayı bekler ve kimse onları çağırmaz. Oysa referansa bakan okur genellikle zaten bir hata almış kişidir; aradığı hücre tam olarak orada durur.

Sözleşmenin makine okunur biçimde tanımlanması ve sözleşmenin testle doğrulanması Web API Tasarımı kursunun konusudur ve burada tekrarlanmaz. Bu derste referans bir sözleşme aracı olarak değil, bakımı gereken bir metin olarak ölçülür: kaç iddia taşıyor, ne kadar dayanıyor, kaç tanesi kurtarılabilir.

Elle Yazmak ve Üretmek

Aynı referans iki yolla var edilebilir.

Elle yazılan referansta her hücre bir insanın yazdığı bir cümledir. Kaynakta bir parametrenin tipi değiştiğinde referanstaki hücre eski tipi göstermeye devam eder; hiçbir şey bu ikisini birbirine bağlamaz. Kaynaktan üretilen referansta ise hücreler metnin içinde değil, kaynağın kendisinde durur ve her yayımda yeniden okunur. Tip değişirse hücre de değişir, çünkü hücre zaten kaynağın kopyasıdır.

Üretimin kurtardığı şey belirlidir: yalnız kaynakta yazılı olan. Bir parametrenin adı, tipi ve varsayılanı kaynaktadır. Bir uç noktanın referansta hangi adla anılacağı kaynakta değildir; bir hata kodunun insan tarafından okunacak adı da çoğu zaman değildir. Bunlar üretimin dışında kalır ve elle yazılan metinde durur. Ölçüm bu ayrımı sayıyla verecek.

Ölçümün varsayımları:

• DT27 — Ölçülen küme, ortak kurgunun referans türüdür: 15 iddia, 13’ü imza, 2’si ad yüzeyinde. Bu karışım değiştirilmez.
• DT28 — Referansın akış ve kavram iddiası yoktur. Referans sıra anlatmaz ve gerekçe kurmaz; bu, türün tanımından gelir ve dersin bir seçimi değildir.
• DT29 — On beş iddia üç bölüme dağıtılır: uç nokta 4, parametre 7, hata 4. Bölümleme yüzey karışımını değiştirmez, yalnız iddiaları adreslenebilir kılar.
• DT30 — Referansın çalıştırılabilir örneğe gömülü iddia oranı 0,00’dır. Referans örnek taşımaz; bu yüzden bayatlayan her referans iddiası sessizdir.
• DT31 — Yüzey sıklıkları değişmez: imza 2, akış 3, ad 5, kavram 12 sürümde bir.
• DT32 — Üretilen referansta imza iddiaları hiç bayatlamaz. Kaynaktan okundukları için kaynakla birlikte değişirler; aradaki gecikme bu ölçümde sıfır sayılır.
• DT33 — Üretim ad yüzeyini kurtarmaz: uç noktanın anıldığı ad ve hata kodunun okunur adı kaynakta durmaz, elle yazılan metinde durur.
• DT34 — Üretim akış yüzeyini de kurtarmaz; ama bu referansta ölçülemez, çünkü referansın akış iddiası yoktur. Akışa bağlı iddialar öteki türlerde ölçülür.
• DT35 — Ölçüm 0, 1, 2, 3, 5, 6 ve 12’nci sürümleri kurar.
• DT36 — Kümenin çözünürlüğü 1/15’tir; tek iddialık farkların altı bu kümeyle savunulamaz.

Ölçüm

"""Arayuz referansi: elle yazilan ile kaynaktan uretilenin omru.

Bolum 1 - referansin 15 iddiasi bolumlere ve yuzeylere nasil dagiliyor.
Bolum 2 - surum boyunca elle yazilan ve uretilen referansta dogru/bayat/sessiz.
"""
SIKLIK = {"imza": 2, "akis": 3, "ad": 5, "kavram": 12}
SURUMLER = (0, 1, 2, 3, 5, 6, 12)
# Referansin 15 iddiasi: hangi bolumde, hangi yuzeye bagli.
# Toplam imza 13, ad 2 - ortak tanimdaki referans karisiminin ta kendisi.
BOLUMLER = {
    "uç nokta":  {"imza": 3, "ad": 1},
    "parametre": {"imza": 7, "ad": 0},
    "hata":      {"imza": 3, "ad": 1},
}
# Referansin gomulu iddia orani sifirdir: referans calistirilabilir ornek tasimaz.
ORNEKLI = 0.00


def iddialar():
    liste, no = [], 0
    for bolum, dagilim in BOLUMLER.items():
        for yuzey, adet in dagilim.items():
            for _ in range(adet):
                no += 1
                liste.append({"no": no, "bolum": bolum, "yuzey": yuzey,
                              "gomulu": ORNEKLI >= 1})
    return liste


def bayat_mi(i, surum):
    return surum // SIKLIK[i["yuzey"]] >= 1


def olc(liste, surum, uretilen):
    """Uretilen referansta imza iddialari kaynaktan geldigi icin bayatlamaz."""
    bayat = [i for i in liste
             if bayat_mi(i, surum) and not (uretilen and i["yuzey"] == "imza")]
    sessiz = [i for i in bayat if not i["gomulu"]]
    return len(liste), len(liste) - len(bayat), len(bayat), len(sessiz)


L = iddialar()
print(f"referans iddiası {len(L)} | örneğe gömülü "
      f"{sum(i['gomulu'] for i in L)}")
print()
print(f"{'bölüm':<12s} {'iddia':>5s} {'imza':>5s} {'ad':>4s} {'akış':>5s} "
      f"{'kavram':>6s}")
for b in BOLUMLER:
    g = [i for i in L if i["bolum"] == b]
    print(f"{b:<12s} {len(g):5d} "
          + " ".join(f"{sum(1 for i in g if i['yuzey'] == y):>{w}d}"
                     for y, w in zip(("imza", "ad", "akis", "kavram"),
                                     (5, 4, 5, 6))))
print(f"{'toplam':<12s} {len(L):5d} "
      + " ".join(f"{sum(1 for i in L if i['yuzey'] == y):>{w}d}"
                 for y, w in zip(("imza", "ad", "akis", "kavram"),
                                 (5, 4, 5, 6))))

print()
print(f"{'sürüm':>5s} {'elle yazılan':>20s} {'üretilen':>20s}")
print(f"{'':5s} {'doğru/bayat/sessiz':>20s} {'doğru/bayat/sessiz':>20s}")
for s in SURUMLER:
    e = olc(L, s, False)
    u = olc(L, s, True)
    print(f"{s:5d} {'{}/{}/{}'.format(*e[1:]):>20s} "
          f"{'{}/{}/{}'.format(*u[1:]):>20s}")

print()
print(f"{'bölüm':<12s} {'6. sürüm elle':>13s} {'6. sürüm üretilen':>17s} "
      f"{'kurtarılan':>10s}")
for b in BOLUMLER:
    g = [i for i in L if i["bolum"] == b]
    e, u = olc(g, 6, False), olc(g, 6, True)
    print(f"{b:<12s} {f'{e[1]}/{e[0]}':>13s} {f'{u[1]}/{u[0]}':>17s} "
          f"{u[1] - e[1]:10d}")

print()
kalan = [i for i in L if bayat_mi(i, 6) and i["yuzey"] != "imza"]
print("6. sürümde üretilen referansta bayat kalan iddialar:",
      [(i["bolum"], i["yuzey"]) for i in kalan])
print(f"üretimin kurtardığı yüzey: imza "
      f"({sum(1 for i in L if i['yuzey'] == 'imza')} iddia) | kurtaramadığı: "
      f"{', '.join(sorted({i['yuzey'] for i in kalan}))} ({len(kalan)} iddia)")

referans iddiası 15 | örneğe gömülü 0

bölüm        iddia  imza   ad  akış kavram
uç nokta         4     3    1     0      0
parametre        7     7    0     0      0
hata             4     3    1     0      0
toplam          15    13    2     0      0

sürüm         elle yazılan             üretilen
        doğru/bayat/sessiz   doğru/bayat/sessiz
    0               15/0/0               15/0/0
    1               15/0/0               15/0/0
    2              2/13/13               15/0/0
    3              2/13/13               15/0/0
    5              0/15/15               13/2/2
    6              0/15/15               13/2/2
   12              0/15/15               13/2/2

bölüm        6. sürüm elle 6. sürüm üretilen kurtarılan
uç nokta               0/4               3/4          3
parametre              0/7               7/7          7
hata                   0/4               3/4          3

6. sürümde üretilen referansta bayat kalan iddialar: [('uç nokta', 'ad'), ('hata', 'ad')]
üretimin kurtardığı yüzey: imza (13 iddia) | kurtaramadığı: ad (2 iddia)

Üretimin Kurtardığı ve Kurtaramadığı

Orta tablo dersin ana sayısını veriyor. Altıncı sürümde elle yazılan referans 0/15; kurtarılan tek iddia yok, on beşinin on beşi bayat. Aynı sürümde üretilen referans 13/15. Fark 13 iddiadır ve tamamı parametre ile uç noktanın imza hücrelerinden gelir.

Alt tablo farkı bölümlere dağıtıyor: parametre bölümü elle 0/7, üretilerek 7/7 — tamamen kurtuluyor, çünkü içindeki her hücre kaynakta yazılı. Uç nokta 0/4’ten 3/4’e, hata bölümü 0/4’ten 3/4’e çıkıyor. Her iki bölümde de kurtarılamayan bir iddia kalıyor.

Kurtarılamayan iki iddianın kim olduğu son satırda açıkça yazıyor: biri uç noktanın referansta anıldığı ad, öteki hata kodunun okunur adı. İkisi de ad yüzeyinde. Üretimin sınırı burada net biçimde çiziliyor: üretim kaynakta yazılı olanı kurtarır, insanın uydurduğunu kurtarmaz. Bir adın ne olduğuna kaynak karar vermez.

Aynı sınır akış yüzeyi için de geçerlidir — çağrıların hangi sırayla yapılacağı kaynaktan üretilemez — ama bu referansta ölçülemez, çünkü referansın akış iddiası 0’dır. Bu bir ölçüm eksiği değil, türün tanımı: referans sıra anlatmaz. Aynı zamanda referansın en büyük boşluğudur ve kursun altıncı dersi tam oradan girecek.

Sessiz sütunu ise dersin rahatsız edici bulgusu. Referansın gömülü iddiası 0 olduğu için her satırda bayat sayısı ile sessiz sayısı aynı: elle yazılanda 15/15, üretilende 2/2. Yani üretim bayat iddia sayısını on beşten ikiye indiriyor ama sessizlik oranını hiç değiştirmiyor — kalan iki iddia da kimseye hiçbir şey söylemeden yanlış duruyor.

Bu, üretimi küçümsemek için değil, ne yaptığını doğru adlandırmak için önemli. Üretim bir doküman denetimi değil, bir kopyalama düzeneğidir: kaynakla metin arasındaki bağı kurar, metnin doğruluğunu kimseye bildirmez. On üç iddia kurtarıldığında geriye kalan iki iddia, tam olarak eskisi kadar sessizdir; üstelik referansın geri kalanı artık güvenilir olduğu için o ikisine kimsenin şüpheyle bakması da beklenmez. Kurtarılan iddialar, kurtarılamayanları gizler.

Kurtarılamayan ikinin hangi iki iddia olduğu ayrıca önemli. Bir önceki bölüm, istemcinin durum koduna göre değil hata koduna göre dallandığını söylemişti; kurtarılamayan iddialardan biri tam olarak o hata kodunun adıdır. Yani 13/15 oranı pratik kurtarışı olduğundan iyi gösteriyor: kurtarılan on üç iddia okurun doğrulamak için baktığı hücrelerdir, kurtarılamayan ikisi ise okurun üzerine kod yazdığı hücreler. Sayı payda üzerinden okunursa üretim kümenin 0,8667’sini kurtarmış görünür; etki üzerinden okunursa en pahalı iki iddiayı olduğu yerde bırakmıştır. Ölçünün kendisi bunu söylemez — ölçü iddia sayar, iddiaların ağırlığını saymaz — ve bu, iddia sayımının bilinmesi gereken sınırıdır.

İkinci ve üçüncü sürüm satırları son bir ayrıntı veriyor: üretilen referans orada 15/15 duruyor, yani ilk üç sürüm boyunca hiç kayıp vermiyor. Elle yazılan aynı noktada 2/13/13. Üretimin kazancı ilk imza değişiminde başlıyor ve beşinci sürüme kadar tam kalıyor; ad yüzeyi ilk kez orada değişiyor ve fark 15’ten 13’e iniyor. Ondan sonra sabit: on ikinci sürümde de 13/15. Üretilen referans bir noktadan sonra daha fazla bozulmaz, çünkü bozulabilecek her şeyi zaten bozmuştur.

Özet

• Referans tablodur, anlatı değil; üç bölümü vardır — uç nokta, parametre, hata — ve hata bölümü en zayıf bölümdür çünkü kimse başarısız yolları çağırmaz.
• Referansın 15 iddiasının 13’ü imzaya, 2’si ada bağlıdır; akış ve kavram iddiası yoktur ve gömülü iddiası 0’dır.
• Elle yazılan referans altıncı sürümde 0/15 verir; kaynaktan üretilen aynı sürümde 13/15 verir. Fark, parametre bölümünün 7/7 ve iki bölümün 3/4’lük kurtarışından gelir.
• Kurtarılamayan 2 iddia ad yüzeyindedir — uç noktanın anıldığı ad ve hata kodunun okunur adı; üretim kaynakta yazılı olanı kurtarır, insanın uydurduğunu kurtarmaz.
• Referans hiç örnek taşımadığı için bayat sayısı ile sessiz sayısı her satırda eşittir; üretim bayatı 15’ten 2’ye indirir, sessizlik oranını hiç değiştirmez.
• İstemci durum koduna göre değil hata koduna göre dallanır; kurtarılamayan iki iddiadan biri odur. İddia sayımı iddiaların ağırlığını saymaz ve bu, ölçünün bilinmesi gereken sınırıdır.

Sonraki Adım

Buraya kadar dört tür ve depo belgeleri ürünün bugünkü hâlini anlattı. Bu dersin tablosu okura yeni bir soru borçlandırdı: elinde 13/15’lik bir referans varken kalan ikisinin ne zaman düştüğünü nereden bilecek? İkinci ders bu soruyu adıyla koymuştu — “hangi sürümde değişti” hiçbir türe düşmüyordu. Sonraki ders o boşluğu kapatan metni ölçer: sürüm notu. Soru şu olacak — değişikliklerin listesi ile değişikliklerin anlamının listesi arasındaki fark, kaç iddiayı okur için tarihlenebilir kılıyor?