--- title: 'API Referansı' source: 'https://academia.sh/tr/kurslar/teknik-yazarlik/api-referansi' course: 'Teknik Yazarlık ve Dokümantasyon' language: tr updated: '2026-08-17T18:10:49+00:00' license: 'CC BY-SA 4.0' --- # API Referansı Referansın 15 iddiasının 13'ü imzaya bağlıdır ve elle yazıldığında altıncı sürümde 0/15 kalır; kaynaktan üretildiğinde aynı sürümde 13/15 kalır, kurtarılamayan 2 iddia ad yüzeyindedir ve referans hiç örnek taşımadığı için bayatlayan iddialarının hepsi sessizdir. Ö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üğü. ```text # 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 ```python """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?