Çoğu zaman yazılım geliştirirken ortaya çıkan ürün yazılımcılar için değilde son kullanıcılar içindir ve bu kişiler teknik olmayan ve sadece UI tarafıyla haşır neşir olan kişilerdir. Ortaya çıkan ürünün iyi bir arayüzü vardır ve son kullanıcı arkada çalışan hangi teknolojiymiş, nasıl çalışıyormuş gibi bilgilerle hiç ilgilenmezler.

Ancak WebApi için bunu söyleyemeyiz. Yazılımcı olarak geliştirmiş olduğunu WebApi projesi end-user için değil bazen kim olduğunu bilmediğimiz başka yazılımcılar içindir. Bu kişiler teknik bilgisi en azından junior developer seviyesinde olan kişilerdir ve ortaya çıkan ürünün interface'i değilde yazılım tarafında ki her bir ince detayı inceleyip kullanacak olan kişilerdir ve sizi eleştirme hakkına da sahiptirler. 

Api'ı kullanacak olan kişiler yazılımcılar olduğundan geliştirmeyi yaparken bir WebApi client'ıymış bakış açısıyla yaklaşıp öyle geliştirme yapmak gerekir ve aslında bir nevi bu bakış açısını da Api'ı kullanan kişilerle de paylaşmış oluyoruz.

Api geliştiriciler genelde geliştirme sırasında şu sorulara odaklanırken ;"Bu servisin ne yapması gerekiyor ?", "Bu servis metodu ne sağlamalı ?", "Content-type json mı, xml mi ?" etc. , Api'ı kullanan kişiler "En az efor sarf ederek bu Api'ı nasıl kullanırım ? etc".

Görüldüğü üzre Api'ı yazan ve Api'ı kullanan kişiler tamamiyle farklı şeylere odaklanıyorlar çünkü farklı bakış açılarıyla Api'ı kullanıyorlar.  Sonuç olarak Api'ı yazan kişiler olarak uygulamayı geliştirirken consume edecek kişilerin yani Api kullanıcılarının bakış açısından bakıp onlar bu APi'ı kullanırken ne gibi sorular sorabilir veya hangi sorunun cevabına en kolay şekilde ulaşabilirler bunu düşünerek hareket etmemiz gerekir.

Peki iyi güzel ama böyle bir Api geliştirmek için neler yapmak gerekir ? Bunun için birçok geliştirici tarafından standart kabul edilen 5 altın kural vardır;

1. Documentation (Dökümantasyon)
2. Stability and Consistency (Kararlılık ve Tutarlılık)
3. Flexibility (Esneklik)
4. Security (Güvenlik)
5. User Acceptance (Kullanıcılar tarafından kabul görmesi)

Rule 1: Documentation 

Yazılım geliştiren kişilerin ortak pek sevmediği şeylerden biri sayfalarca analistler tarafından yazılmış dökümanları okumaktır. Sizde sevmiyorsunuz dimi ?.. :)  

İyi bir dökümantasyon Api için olmazsa olmazlardandır ve çoğu zaman Api'ları geliştirren kişiler olarak bu iş biz developer'lara bırakılmıştır. Kullanıcı tarafından düşünelim bir bankada çalışıyorsunuz ve banka radikal bir karar alarak bazı servislerini dışarıya açma kararı aldı ve başladınız Api metodlarını yazmaya. Api'lar prod'a alınıp kullanıma sunulduktan sonra kullanmak isteyen kişilerin ilk başlayacakları yer Api ile ilgili yazılan dökümanları okumaktır.  Yani birinin sizin Api'ınızı kullanmasını istiyorsanız ilk yapmanız geren şey dökümantasyon yazmaktır çünkü kullanıcıların ilk bakacakları şey budur.

Peki iyi bir dökümantasyonu nasıl yazarız ?

Yazılımla projeleri ile ilgili dökümanlarda genelde; hangi sırasıyla metodların çağrılacağı, metod parametreleri, değişken tipleri, request, response class'ları etc. ve dökümantasyon oluşturmak içinde bir çok tool'da bulunmaktadır aynı zamanda kendimizde bunları basit bir template belirleyerek yazabiliriz. 

Ancak harika yazılmış bir dökümanı üstte bahsettiğimiz yaygın olarak kullanılan döküman yazma tekniklerinden ne ayırır diye soracak olursa Api'ın kullanım örnekleri ve iyi bir eğitim içeriği. Bu ikisi Api'ı kullanan kişiler için en önemli iki şeydir diyebiliriz çünkü son kullanıcı için gerçek bir örnek üzerinden ve takıldığı noktaları eğitim içeriğine bakarak en hızlı ve kolay şekilde öğrenecektir. Ancak yazdığımız dökümanın şeması ve yazdığımız örnek kodların karmaşık olmamasına da dikkat etmeliyiz. Döküman yazıyoruz diye kullanıcıya 300 sayfalık bir roman veya 15 class'lık bir örnek projede yazmamalıyız :)

Dökümantasyon işiniz bittikten sonra yapabiliyorsanız yapmış olduğunuz örnek Api kullanım projelerini ve dökümanları çevrenizdeki developer'lara gönderin ve feedback'ler almaya çalışın. Gelen feedback'ler doğrultusunda da yazmış olduğunuz dökümanıdaha user-friend hale getirebilirsiniz.  

Yaptıkları dökümanları harika bulduğum birkaç firma var ki bunlar kendi sektörlerinde en iyiler bile değiller ancak gerçek bir Api dökümanı nasıl olmalı sorusuna verilecek en iyi cevabı vermiş firmalar;

• Twilio,
• Django,
• MailChimp 

Rule 2: Stability and Consistency

Daha önce Facebookûn Api'larını kullandıysanız ne sıklıkla Api'ları değiştirdiklerini bilirsiniz. Sürekli olarak bir güncelleme yayınlıyorlar ve çalışan birçok uygulama da patlıyor çatlıyor. Facebook'un ne kadar başarılı bir ürün olduğuna herkes hemfikirdir ancak başarılı olmalarının sebebi son derece iyi bir Api'a sahip oldukları değil milyarları geçen kullanıcı sayısı sahip olmaları ancak iş Api konusuna gelince developer'lar için bazen hayatı zindan ettikleri oluyor. Muhtemelen sizlerin geliştirdiği Api'lar milyarlarca kullanıcı tarafından kullanılmicak ancak o bakış açısıyla geliştiriyor olmakta fayda var. Yeni sürüm yayınladığınızda eski versiyonlara desteği en azından birkaç yıl daha sürdürüyor olmak gerekir en azından mevcut kullanıcıları en iyi şekilde yeni versiyondan haberdar ederek onların yeni versiyona geçmelerini sağlamak gerekir.

Örnek üzerinden gitmek gerekirse ; farz edelim ki http://www.canertosuner.com/api/getUsers/  şeklinde tanımlı JSON formatında response dönen ve yaklaşık 10 bin kişi  tarafından kullanılan bir Api'ımız var diyelim. Api'ı production'a aldıktan aylar sonra dönen responsları değiştirdiniz ve bu Api'ı kullanan kişileri de etkileyen bir değişiklik olsun. Bu şu demek; 10 bin kişinin geliştirdiği 10 bin uygulamaların patlaması demek. Bunun çözümü tabii ki de uygulamaya yeni versiyon çıkmamak değil bir ürün aldığı update'ler ile daha iyi olur. Bunun çözümü için Api'ınıza basit bir versiyon kontrolü koymak ve eski versiyonlara desteği sürdürmek.( http://www.canertosuner.com/api/getUsers?version=2 yada http://www.canertosuner.com/api/v2/getUsers ) .Böylelikle hem eski versiyonu kullananlar yeni versiyona geçene kadar uygulamalarının çalışmalarını sağlayabilirler hemde Api'ı yeni kullanmaya başlayacak olanlar direkt olarak son versiyondan başlarlar.

Api'ınızın Consistent yani tutarlı olması da son derece önemlidir. Api'ınızın geriye döndüğü response class'larının ortak bir base class içerisinde olmasına özen gösterin. Çünkü bu class sayesinde metodun döndüğü response dışında Api kullanıcısına farklı verilerde döndürebilirsiniz. Daha önce kullanmış olduğum bazı Api'larda tutarlılık neredeyse hiç yoktu. Sürekli olarak yeni gelen versiyonlarda parametre isimleri değişiyor, metod isimleri değişebiliyor, bir önceki metodda UserID'yi int gönderirken bir sonraki metodda string olarak istiyorlardı, hata mesajları sürekli olarak farklı formatta geliyordu vs. gibi örneklerle karşılaşmak mümkün. Bu gibi durumlara dikkat etmek gerekiyor. Ortak kullanılan parametreler tek bir yerden yönetilebiliyor olmalı ve major değişiklikler kolay kolay uygulanmamalı veya uygulandığında Api'ı kullanan kişiyi etkilenmesinden kaçınılmalı.

Son olarak yayınlamış olduğunuz yeni versiyonlarda iyi bir changelog yayınlayıp mevcut kullanıcılarınızı bilgilendirmeniz gerekir. Böylece kullanıcılar nasıl upgrade edeceklerini öğrenmiş olurlar ve Api uygulamanızda çok büyük major değişikliklere gitmemeye özen gösterin veya bunu kullanıcıları en az seviyede etkileyecek şekilde yapın ve tutarlılığı korumaya çalışın.

Rule 3: Flexibility

Yazmış olduğumuz Api'ların flexible yani esnek olması oldukça öçnemli bir konudur.Peki ama esnek derken neyi kastediyorum ?

Garbage in, garbage out (GIGO) programcılar tarafından iyi bilinen bir technical-term dür. Kısaca "input olarak ne verirsen output'un ona göre değişiklik gösterir" veya ne ekersen onu biçersin". Hadi biraz daha basit söyleyelim programa yanlış bir request'te bulunursanız response'unuzda yanlış olacaktır. GIGO yu örnek olarak vermemin sebebi aslında Web Api tarafında request response ilişkisine dikkat çekmek istemem. 

Günümüzde bir çok Api doğru düzgün bir JSON desteği bile bulunmamakta ancak iyi bir Api'ın sadece JSON değil bunu yanında YAML, XML vs. gibi formatlar içinde desteği bulunmalıdır ve bunlardan hangisini return edeceği bilgisini de aslında Api kullanıcılardan yani client'lardan parametre olarak almalıdır. Örnek olarak http://www.canertosuner.com/api/getUsers?Format=JSON yada bu bilgiyi header'a parametre olarak eklemek aslında en doğru kullanımdır diyebiliriz Accept: application/json .

Bu kullanım sadece kullanıcıya dönecek olan response için değil aynı zamanda kullanıcının size göndereceği Post metodlarında body de bulunan request parametreleri içinde geçerlidir. Bir kulalnıcı JSON olarak gönderirken diğer bir kullanıcı XML olarak göndermek isteyebilir ve böyle bir esnekliğe sahip olabilmek oldukça önemli bir ayrıcalıktır.

Api'ınızın OData özelliğine sahip olması da bir o kadar önemlidir. OData ile Api'nızın döneceği respons'lara kullanıcılar tarafından filtreleme yapma şansı sunarsınız ve böylece kullanıcının istemediği bir veriyi dönmemiş olursunuz. Örneğin A kullanıcısı GetProducts metodundan sadece ProductID'lerini almak isterken B kullanıcısı ProductName ve ProductID alanlarını almak isteyebilir. OData bu gibi durumlar için son derece filexible(esnek) bir kullanım sunar.

Rule 4: Security

Güvenlik bir WebService & WebApi projesindeki en önemli noktalardan biri ancak öyle Api'lar var ki otantike olmak nerdeyse bazen imkansız oluyor. Tamam güvenlik önemli ama öyle katı ve karmaşık kurallar koyarak Api yazan firmalar var ki bazen birbiri ile ilişkili Api' metodları için 2-3 çeşit güvenlik algoritması kullandığımız olabiliyor ve ortada dökümanda yoksa nasıl requestte bulunacaksın, nasıl response alacaksın hepsi belirsiz. Bir Api developer olarak Api'ı kullanan kişiler için nasıl authenticate ve authorize olunur bilgilerini içeren kolay ve açıklayıcı örneklerle anlatıyor olmamız gerekir. 

Günümüz Web Api'larının çoğunda ortak olarak token-based authentication kullanılmakta. Kısaca; kullanıcı yapmış olduğu ilk requestte Api'a bazı güvenlik parametreleri geçer ve Api'da ona random generate edilmiş olan token bilgisini döner ve client bütün session'ı boyunca aynı token üzerinden request atıp response almaya devam eder. 

Token dışında OAuth 2 + SSL de Api'ınızı güvenli hale getirmek için yapılabilecek diğer seçenekler arasındadır. SSL her halükarda kullanıyor olmamız gerekir bunun yanında OAuth 2'yi de server-side'da uygulamakta oldukça basittir ve  OAuth 2'nin hemen hemen bütün yaygın kullanılan programlama dilleri için kütüphaneleri de bulunmaktadır.

Bunlarla birlikte güvenlik için dikkat edilmesi gereken birkaç konu dha bulunmaktadır;

• Api'larda genellikle update, insert, delete gibi işlemler yapılabilmektedir. Bu işlemleri yapan metodları public hale getirip bütün kullanıcıların kullanımına sunarken dikkat edilmesi gerekmektedir. Her kullanıcının şöyle bir Api çağrısı yapamıyor olması gerekir "/user/delete/<id>" . Bununla ilgili her bir kullanıcı için Whitelisting Functionality bilgisi oluşturup bu listede belirtilen kurallara göre request validation işlemleri yapılabilir. 
• OData kullanırken de select işlemleri yapılırken kullanıcının sahip olmasını istemediğimiz bilgiler için request'te bulunduğunda 406 Not Acceptable Response şeklinde status kodlar dönebiliriz. 
• Cross-Site Request Forgery (CSRF) isteklerine akrşı Api'ı korumalıyız. Session veya cookie bazlı bir authentication yapımız var ise Api'ımızı CSRF ataklarına karşı koruduğumuzdan emin olmalıyız. Bununla ilgili faydalı dökümanları The Open Web Application Security Project (OWASP) da bulabilirsiniz. 
• Resource dosyalarına olan erişimi yönetiyor olmamız gerekir. Örnek olarak bir banka kredi kartlarını tutan Api yazdınız ve Api içerisindeki bir dosyada kredi kartı görselleri bulunmakta. Herhangi bir kullanıcı gidipte  /account/card/view/152423 şeklinde bir istekte bulunup erişmemesi gereken bir resource dosyasına erişmemelidir.
• Bütün request'leri validate ediyor olmamız gerekir. Her bir request'in kendine özgü parametreleri bulunur ve kullanıcı sürekli olarak saçma sapan request'lerde bulunduğunda örnek olarak; userId miz 4608 olsun ve user bilglsini getiren metoda 4608 den başlayıp random sayılar üreterek ( /account/getUserInfo/4609) başka kullanıcıların bilgileri için request'te bulunduklarında Api'ımızın bir şekilde bir güvenlik kontrolü olup bu kullanıcıyı tespit edip engellemelidir.

Rule 5: User Acceptance

Beşinci ve son kural aslında bu beşli arasındaki en önemli kural diyebiliriz. Bu kural ilk 4 kural boyunca bahsettiğim bütün şeylerin aslında bir ürün olarak hazırlanıp kullanıcıya sunulması ve kabul görmesini içermekte. Örneğin iyi bir dökümantasyon, kolay entegre edilebilir güvenlik adımları, yazdığımız Api'metodlarını tutorial'larla süsleyip max 15 dakikada kullanıcılar tarafından entegre edebilmelerini sağlama gibi durumlar diyebiliriz.

Api'ın kullanıcılar tarafından daha kolay kabul görmesini sağlayacak bazı spesific tavsiyeler saymak gerekirse;  

• Kullanıcıların dökümantasyonda belirtilenlere göre Api'ınızı ilk denemeden sonra entegre edebildiğinden emin olun.
• KISS - Keep it Simple Stupid anlayışına göre hareket etmeye çalışın. Fantastik authentication yöntemlerinden kaçının, SOAP, JSON, REST'i yeniden yaratmaya çalışmayın veya bütün platformlar tarafından kabul görmemiş herhangi bir yöntem kullanmayın.
• Service arayüzü için dil spesifik library'i desteği vermeye çalışın. Otomatik olarak bu işlemi yapan güzel tool'lar da mevcut (Alpaca veya Apache Thrift gibi).
• Gereken sign-up işlemlerini en basit şekilde yapın. Api'ınız bir open-source proje değilse ve sign-up & register gibi işlemler varsa bunları olabildiğince basite indirgeyip biran önce kullanıcıları yormadan api'ınınzın bulunduğu yere yönlendirin. Eğer sizin için extra bir maliyeti yoksa sign-up with social media account (facebook, google, twitter etc) özelliği sunabilirsiniz. 
• "Satış sonrası destek" sağlayın. Bug'sız uygulama olmaz ve Api'ı kullanan kişiler bug veya herhangi bir sorun ile karşılaştıklarında en kısa ve kolay şekilde bunları size iletmesini sağlayın. Bu bir forum sitesi veya e-mail sistemi olabilir size kolayca raporlayabilsinler. Sorunu giderip yeni versiyon çıktıktan sonrada ilgili kişileri tekrardan bilgilendirmeyi ihmal etmeyin.

Özetle..

Iot (Internet of Things) ile birlikte hayatımızda kullanacağımız IP alıp internete çıkabilen bütün teknolojik ürünler WebService & Api ile haberleşiyor olacaklar ve beraberinde birçok yeni Api'lar yazılmasına ihtiyaç duyulacak. Bugünün verilerine göre düşünürsek; binlerce api & web service var ancak sıkıntılı olan şey kullanımları gerçekten kolay değil. Sebep olarak SOLID prensiplerine pek uymayan yazılım anlamında zayıf tasarımlı projeler olması, dökümantasyon tarafının yeterli düzeyde veya yeteri kadar kolay anlaşılabilir olmaması, örnek kod parçacıkları içermemesi, raporlanmasına rağmen çözülmeyen bug'lar etc.. bir sürü sıralayabiliriz.

Yukarıda belirtilen 5 altın kural bir çok kişi tarafından aslında ortak dile getirilen başlıklar ve Api projesi geliştirirken uyulması gereken kurallar olarak belirtilmekte. Eğer bizlerde bundan sonra yazacağımız Api'larda birazcıkta olsa bu kurallara uygulayarak hareket edersek her şey hem Api geliştiriciler hemde Api kullanan kişiler için daha kolay olacaktır.