Mikroservis Yazı Serisi 10 - Documenting Contracts

     Selamün Aleyküm Arkadaşlar,

    Serinin onuncu yazısında dokümantasyon konusunu ve uri tasarımını ele alacağız. Diğer konulara oranla az önemli gibi gözükse de büyüyen projelerde bu konu beklediğimizden çok daha önemli hale gelmektedir. Özellikle farklı takımların sürekli senkron veya asenkron bir iletişimle sürdürmesi yerine bu konuya eğilmek çok daha kıymetli olacaktır. Ayrıca sonradan projelere katılacak olan arkadaşlara da can simidi olabilir. Hazırsak başlayalım.

    Bugünkü konumuz da diğer konular gibi mikroservise has bir konu değildir, ancak yapı büyüdükçe bu yapılan işlerin önemi daha iyi anlaşılacaktır. Belirli bir standardın dışına çıkıldı mı bunları yönetmek oldukça zorlaşıyor. Ekipler arası geçişler, değişimler olsa da aslında bütün projelerin tek bir ekipten çıkıyormuşçasına düzenli görünmesi o işteki başarımızı da artırmaktadır.

    İyi bir Uri tasarımında öncelikle tutarlılık olmalıdır. Uçlarda nasıl bir isimlendirme takip edeceğiniz ya da fiiller ile başlamak yerine kaynakların isimlerini baz alacağınız gibi kurallarınızın olması önemli. Bahsedilen konuda "best practice"ler zaten mevcut. Onları takip etmekte de fayda var. Bir önceki yazımızda bahsettiğimiz konulardan biri olan versiyonlama yine çok önemli bir nokta. HTTP metodlarını doğru şekillerde kullanmak da önemli noktalardan biridir.

    API spesifikasyonu dediğimiz API uçları dokümante etmek çok önemli. Open API bunları belirli bir standarda getirip Swagger gibi araçlarla bunu hızlıca çözebiliriz. Neredeyse tüm projelerin vazgeçilmezi olması ise mutluluk verici. Ayrıca sadece Rest api için değil, GraphQL ve hatta gRPC için farklı araçlarla bunları bize sağlayabiliyor.

    Önceki yazımızda ele aldığımız "back compatibility" ve CDC testleri ile önceki versiyonlara ait uçları bozmamak, istemcilerin doğru bir şekilde iletişimlerine devam etmeleri açısından önemlidir. 

    Dokümanları yazmak çoğu geliştiricinin ihmal ettiği ve belki de sıkıldığı bir şey olsa da daha da zoru maalesef o dokümanı güncel tutabilmektir. Güncel olmayan doküman bazen olmayan dokümandan daha can sıkıcı olabiliyor. Çünkü bizler onu doğru kabul edip bazı yorumlarda veya çıkarımlarda bulunarak yanlışlığa sebebiyet verebiliriz. Geliştirici yazdığı kodun testini, dokümantasyonunu yazmadan ve onu canlıya göndermeden işinin bitmediğini sürekli hatrında bulundurmalıdır.

    Bir önemli nokta da yazdığımız dokümanları yazıyormuş olmak için yazmamak. Eğer böyle yapıyorsak belki de hiç yazmamak daha iyidir mi demeliyiz yoksa kötü de olsa bir yerden başlayıp onu alışkanlık haline mi getirmeliyiz kısmını sizin yorumlarınıza bırakıp iyi dokümanın bazı özelliklerine kısaca göz atalım.

• Tüm uçlar detaylı olarak alınmalı, gönderilen parametreler ve cevap anlatılmalıdır.
• Uçların hangi durumlarda hangi status kodlarını da döneceği önemlidir.
• Varsa hata kodları ve bu kodlarının ne anlama geldiği ve hangi koşullarda karşılaşıldığı belirtilmeli.
• Auth sistemlerinin gereksinimleri belirtilmelidir.
• Belirli isteklerden sonra rate limit koşulları varsa bunları da belirtmek iyi olur.

    Özetle iyi ve tutarlı bir dokümantasyon sadece geliştiricilerin değil, tüm ekibin en önemli işlerinden biri olmalıdır. Bunu şirketin veya en azından ekibin kültürü haline getirdiğinizde ne kadar başarılı işler ortaya çıkardığınızı ileride çok daha net bir şekilde kendiniz de göreceksiniz. 

    Yazıyı birer ayet-i kerim ve hadis-i şerif ile bitirelim.

“Hiç bilenlerle bilmeyenler bir olur mu? Ancak akıl sahipleri öğüt alır.”                                                                                                               (Zümer Suresi, 9. Ayet) 

"Bir kimse ilim öğrenmek için bir yola girerse, Allah ona cennete giden yolu kolaylaştırır."                                                             (Müslim, Zikir, 38; Ebu Davud, İlim, 1; Tirmizi, İlim, 2)