API dokümantasyonunu Excel ya da PDF olarak hazırlayıp e-postayla paylaşma yöntemi bize fazlasıyla tanıdık gelir.
Bir sorun çıktığında sorumlu kişiye ulaşır, eski e-postaları arayıp müşterinin elindeki dokümanın sürümünü kontrol ederiz. Değişen içerikleri yeniden açıklar, güncellenmiş dokümanı gönderdikten sonra doğru yansıtılıp yansıtılmadığını bir kez daha teyit ederiz.
Bu süreci o kadar çok tekrarladık ki bunun zaten yapılması gereken iş olduğunu düşünmeye başladık.
Ama sorun tek bir hatalı dokümanla bitmez.
API her değiştiğinde yeni dosyalar ve e-postalar, müşteri bazlı istisnalar ve sorumlu kişinin hafızası birer birer birikir. Başta küçük bir rahatsızlıktır; ancak zaman geçtikçe hangi dokümanın esas alınacağını doğrulamak zorlaşır, sorunu çözmek için gereken kişi ve zaman da birlikte artar.
Müşteri önceki sürümün istek formatına göre geliştirme yaparsa entegrasyon hataları ve yeniden çalışma ortaya çıkar. Zorunlu alanlar ya da kimlik doğrulama yöntemi farklı aktarılırsa geliştirme takvimi gecikir; API hâlihazırda canlıda çalışıyorsa bu, veri hatalarına veya kesintilere de yol açabilir.
Sorun ortaya çıktıktan sonra ancak iç geliştirme ekibiyle müşterinin farklı dokümanlara baktığı fark edilir.
O noktadan itibaren geliştirici yürüttüğü işi durdurup nedeni araştırır. Operasyon sorumlusu eski dokümanları ve iletim geçmişini arar, müşteri de kendi implementasyonunu ve kendisine iletilen spesifikasyonu yeniden doğrular. Tek bir doküman uyumsuzluğu, birden fazla kişinin işini aynı anda durdurur.
Buna rağmen sorunların çoğu telefon, e-posta ve mesajlaşma araçlarıyla sessizce çözülür.
Birileri düzeltilmiş dosyayı yeniden gönderir, birileri müşteriye durumu açıklar, geliştirici de aceleyle istisna işleme ekler. O anki sorun çözülür; ancak neden ortaya çıktığı, hangi müşterilerin etkilendiği ve aynı sorunun tekrarlanmaması için neyin değiştirildiği organizasyonda kalmaz.
Bu süreçte harcanan zaman, aslında geliştirme ve ürün iyileştirmeye ayrılması gereken zamandır.
Daha büyük sorun ise tüm bu sürecin belirli bir sorumlu kişinin deneyimine, hafızasına ve posta kutusuna bağlı olmasıdır. Sorumlu kişi yerinde olmadığında ya da şirketten ayrıldığında organizasyon, e-postaları ve mesajlaşma kayıtlarını karıştırarak işi yeniden ayağa kaldırmak zorunda kalır.
Yönetilmeyen API dokümantasyonu ortadan kaybolmaz. Organizasyonun içinde ve dışında kalmaya devam ederek görünmez bir dokümantasyon borcuna dönüşür.
Belki de sorunları gerçekten çözmüyoruz; sorun her ortaya çıktığında onu insanların zamanı ile kapatmaya alışmış durumdayız.
Bu sorunları gerçek iş süreçlerinde yaşamış biri olarak SpecBridge’i geliştirdim.
SpecBridge, yalnızca API dokümantasyonu yazmaya yarayan bir araç değildir. Dokümandaki değişiklikleri gözden geçiren ve yalnızca onaylanmış sürümleri müşterilere ve dış iş ortaklarına dağıtan bir API dokümantasyonu operasyon aracıdır.
Mevcut Swagger’ın yerini almak yerine, Swagger/OpenAPI ve Postman Collection’ı içe aktarıp dışa iletim sürecinde ortaya çıkan sorunları yönetmeye odaklandım.
- Mevcut dağıtım sürümü ile düzenlenmiş sürüm arasındaki farkları karşılaştırma
- Değişikliklerin gözden geçirilmesi ve onaylanması
- Taslak ile müşterinin gördüğü dağıtım sürümünü ayırma
- Müşteri bazında dokümantasyon görünürlük kapsamını yönetme
- Herkese açık bağlantı için parola ve son kullanma tarihi belirleme
- Aynı bağlantıda onaylanmış en güncel dokümanı sunma
Müşteriye her seferinde yeni bir dosya göndermeye gerek kalmadan, iç incelemesi tamamlanmış dokümanı mevcut bağlantıya yeniden dağıtabilirsiniz.
Geliştiriciler doküman arama ve yeniden iletme gibi tekrarlı işleri azaltabilir; organizasyon ise API dokümantasyonunu belirli bir sorumlu kişinin hafızasına değil, kayıt altına alınmış değişiklik geçmişine ve dağıtım kriterlerine göre yönetebilir.
Şu anda SpecBridge’i gerçek API dokümantasyonu operasyonlarında kullanacak ve dürüst geri bildirim verecek partnerler arıyorum.
API dokümantasyonunu Excel ya da PDF ile yönetiyorsanız veya API her değiştiğinde dokümanı müşterilere yeniden iletiyorsanız, şu anda kullandığınız tek bir dokümandan başlayarak birlikte doğrulama yapmak isterim.
İyi yapılmış özelliklere övgü duymaktan çok, gerçek operasyonda rahatsız eden noktalar, gereksiz süreçler ve eksik özellikler hakkında dürüst görüşler duymak istiyorum.
Henüz yorum yok.