API Tasarlarken Öğrenilen Acı Dersler

API Tasarlarken Öğrenilen Acı Dersler

API tasarlamak genelde “endpoint yazmak” gibi görünür.

Bir şey isterler, bir şey dönersin, çalışır. İlk başta her şey yolundadır.

 

Sonra kullanıcı sayısı artar.

İstemciler çoğalır.

“Buna da ihtiyaç var” denir.

Ve bir noktada fark edersin:

Sorun kodda değil, kararlardadır.

 

İşte API tasarlarken genelde can yakarak öğrenilen dersler tam da burada başlar.

 

 

“Şimdilik böyle” kararları en pahalı olanlardır

 

API tasarımında en masum görünen cümle şudur:

 

“Şimdilik böyle yapalım, sonra değiştiririz.”

 

Ama API’ler “sonra”yı pek sevmez.

 

Bir endpoint kullanıma girdiyse:

• Client’lar ona bağlanır

• Dokümantasyon ona göre yazılır

• Geriye dönmek maliyetli hâle gelir

 

Kod değişir ama sözleşme kalır.

Bu yüzden geçici kararlar API dünyasında genelde kalıcıdır.

 

 

İsimlendirme sandığından daha önemlidir

 

/getUserData, /fetchUser, /userInfo…

 

İlk başta çok fark etmez gibi durur.

Ama zamanla şunu yaşarsın:

• Aynı şeyi yapan ama farklı isimli endpoint’ler

• Ne işe yaradığını adından anlamadığın yapılar

 

API’de isimlendirme sadece estetik değildir.

Okunabilirliktir.

 

Kötü isimler, kötü deneyim yaratır.

 

 

Her şeyi esnek yapmak çözüm değildir

 

“İleride lazım olur” diyerek:

• Çok genel endpoint’ler

• Her şeyi alan payload’lar

• Fazla opsiyonlu parametreler

 

tasarlamak cazip gelir.

 

Ama bu esneklik:

• Kullanımı zorlaştırır

• Hataları artırır

• Davranışı belirsizleştirir

 

API tasarımında netlik, esneklikten daha değerlidir.

 

 

Hataları net tanımlamamak en çok geri dönen konudur

Başta şöyle dersin:

 

“Şimdilik 500 dönsün.”

 

Sonra:

• Frontend ne olduğunu anlayamaz

• Log’lar şişer

• Aynı hata defalarca sorulur

 

İyi bir API sadece “doğru cevap” vermez,

yanlışta da ne olduğunu söyler.

 

Hata yönetimi sonradan eklenmez.

En başta düşünülür.

 

 

Versiyonlama ertelendikçe korkutucu olur

“v1 eklemeyelim, gerekirse sonra yaparız.”

 

Sonra API büyür.

Client’lar çoğalır.

Değişiklik ihtiyacı gelir.

 

Ama artık:

• Geriye dönmek zor

• Herkes farklı şey bekliyor

• Kimse kırılmasını istemiyor

 

Versiyonlama başta küçük bir detay gibi görünür.

Geç kalındığında ise en acı derslerden biri olur.

 

 

Dokümantasyon yazmamak sana geri döner

 

“Zaten basit, herkes anlar.”

 

Hayır, anlamaz.

• Sen unutursun

• Başkası yanlış kullanır

• Aynı sorular tekrar tekrar gelir

 

Dokümantasyon başkaları için değil,

gelecekteki sen içindir.

 

 

Asıl ders: API kod değil, iletişimdir

 

API tasarlarken genelde teknik düşünürüz.

Ama API aslında:

• Bir ekipyle

• Bir ürünle

• Bir gelecek senaryosuyla

 

kurulan iletişimdir.

 

Yanlış anlaşılırsa, teknik olarak doğru olsa bile başarısız olur.

 

 

Son söz

API tasarlarken öğrenilen acı derslerin çoğu,

kod yazarken değil,

karar alırken ortaya çıkar.

 

Daha yavaş karar almak,

daha net olmak,

daha az varsaymak…

 

Bunlar API’yi “çalışan” değil,

yaşayan bir yapı hâline getirir.

 

Ve çoğu geliştirici şu noktada hemfikirdir:

API’yi ikinci kez yazmak zorunda kalmak,

ilkinde acele etmekten çok daha acıdır.