API / SWAGGER NEDİR ?
Merhabalar :) Bu yazımda sizlere API’nin ne olduğundan, rest, soap kavramlarından ve swagger API’nin kullanımından bahsedeceğim. Ben yazarken daha çok öğreniyorum, umarım siz de okurken bir şeyler öğrenebilirsiniz. Keyifli okumalar :)
API(Application Programming Interface) yani Uygulama Programlama Arayüzü. Bir uygulamaya ait işlevlerin başka bir uygulamada da kullanılabilmesi için oluşturulmuş bir arayüzdür. İki yazılımın veya veritabanının birbiri ile sorunsuz çalışabilmesini ve en sağlıklı bir şekilde birbiri ile iletişime geçmesini sağlar. API, yazılım bileşeniyle olan etkileşimlerin bir özelliğidir.
Bu da örnek olarak şu anlama gelebilir. Yemek yapmanın bir yazılım olduğunu hayal edelim. Yemek yapmanın API’si yemeğin nasıl yapılacağı hakkında bilgi verir. Tecereyi çıkar, kepçeyi al, suyu ısıt vs. Örneğin yemeği yapmaya başlamak için ocağı yakarız. API o yemeğin içine neler koyduğunuzu bilmek zorunda değildir. Bu nedenle fasulye yapmayı öğrendiyseniz, tamamen yeni bir dizi beceri öğrenmek zorunda kalmadan API sayesinde nohut yemeğini de yapabilirsiniz :)
API Türleri Nelerdir?
- Open API (Public API) : Minimum kısıtlama ile geliştiriciler ve diğer kullanıcılar tarafından herkesin kullanımına açık API’lerdir. Kayıt, API Anahtarı veya OAuth kullanımını gerektirebilir veya tamamen açık olabilirler. Verilere veya hizmetlere erişmek için harici kullanıcılara odaklanırlar.
- Internal API (Private API) : Harici kullanıcılardan gizlenir ve yalnızca dahili sistemler tarafından açığa çıkarılır. Internal API’ler, şirket dışındaki tüketim için değil, daha çok daha iyi üretkenlik ve hizmetlerin yeniden kullanımı için farklı dahili geliştirme ekiplerinde kullanılmak üzere tasarlanmıştır.
- Partner API : Stratejik iş ortaklarına veya stratejik iş ortakları tarafından sunulan API’lerdir. Herkese açık değildir ve bunlara erişmek için özel yetkilere ihtiyaçlar vardır. Open API’ler gibi, Partner API’ler de buzdağının görünen kısmıdır çünkü bunlar en görünür olanlardır ve şirket sınırlarının ötesinde iletişim kurmak için kullanılırlar.
- Composite API : Composite API’ler birden çok veri veya hizmet API’sini birleştiren API’lerdir. Bir API oluşturma aracının API düzenleme yetenekleri kullanılarak oluşturulurlar. Geliştiricilerin tek bir aramada birkaç uç noktaya erişmesine izin verir.
REST NEDİR ?
REST( Representational State Transfer) istemci-sunucu arasında hızlı ve kolay şekilde iletişim kurulmasını sağlayan bir servis yapısıdır. REST, servis yönelimli mimari üzerine oluşturulan yazılımlarda kullanılan bir veri transfer yöntemidir. HTTP üzerinde çalışır ve diğer alternatiflere göre daha basittir, minimum içerikle veri alıp gönderdiği için de daha hızlıdır. İstemci ve sunucu arasında XML veya JSON verilerini taşıyarak uygulamaların haberleşmesini sağlar. REST standartlarına uygun yazılan web servislerine RESTful servisler denir.
SOAP NEDİR ?
SOAP(en: Simple Access Protocol ,tr: Basit Nesne Erişim Protokolü) en temel anlamda, internet üzerinden küçük miktarda bilgileri yada mesajları aktarma protokolüdür. SOAP mesajları XML formatındadırlar ve genellikle HTTP(Hyper Text Transfer Protocol) protokolü(bazen de TCP/IP) kullanılarak gönderilirler. SOAP ,XML tabanlı kullanıma mecbur bırakır. Bu konuda esnek değildir.
SWAGGER API
Swagger, yazılım geliştiricilerin Restful api’lerini tasarlamasına, oluşturmasına, belgelemesine ve rahat bir şekilde kullanmasını sağlayan doküman oluşturma tool’u dur. Swagger, otomatik dokümantasyon ve test senaryosu ile birlikte yaygın bir şekilde kullanılmaktadır.
Neden Swagger Kullanmalıyız ?
API geliştirmede dokümantasyon önemli bir ihtiyaçtır. Yazmış olduğunuz servisleri kullanacak diğer geliştiricilere ya da herkese açık olarak paylaşmak istediğinizde, API metotlarınızın ne işe yaradığı, nasıl çalıştığı ile ilgili gerekli bilgiyi de paylaşmalısınız. API dokümanınızın manuel olarak el ile yazmak hem büyük bir vakit kaybı hem güncel tutmanız imkansıza yakındır. Bu sorunlara çözüm olarak swagger işimizi büyük ölçüde hafifletmektedir.
Swagger, yazmış olduğumuz Rest API’lerin incelenmesi, anlaşılması ve test edilmesini sağlayan bir arayüz sağlamaktadır. İsterseniz şimdi bir örnek ile nasıl projelerimize dahil edeceğimize geçelim.
Yapacağımız örnekte .Net Core 3.1 Web Api kullanılarak yapılmış olan bir projeye swagger ekleyeceğiz.
Öncelikle projemize Nuget Packages aracılığıyla Swashbuckle.AspNetCore kütüphanesini projemize dahil ediyoruz.
Ardından Startup.cs dosyasına ilgili ayarlamalarımızı yapıyoruz.
Startup.cs / ConfigureServices :
Startup.cs / Configure :
Burada dikkat etmemiz gereken en önemli nokta ConfigureServices içerisinde tanımlamış olduğumuz SwaggerDoc “Web” parametresi ile Configure içerisindeki SwaggerEndpoint “Web” aynı ada sahip olmalıdırlar.
Uygulamayı çalıştırıp url’in sonuna /index.html yazarak swagger’in oluşturmuş olduğu dokümanı görüntüleyebiliriz.
Swagger üzerinde Api’lerimizi çalıştırmak için yukarıda görüldüğü gibi Try It Out butonunu kullanırız.
Sonuç Olarak
API, ticari faaliyetlerinizi hızlandırmanıza, markanızın erişimini artırmanıza, alışveriş yapan kişilerinizi istedikleri ürünlere bağlamanıza ve çok daha fazlasına yardımcı olabilecek güçlü bir araçtır.
