ASP .NET WEB API
Last updated
Last updated
API; "Application Programming Interface" - uygulama geliştirme arayüzü anlamına gelir ve sahip olduğumuz service veya verileri dış dünyaya açıp başka uygulamaların/platformların kullanımına sunmak için belli kurallar çerçevesinde tanımlamalar yaptığımız arayüz dür.
Microsoftun Web servis mimarisi için geliştirdiği web ve mobil tabanlı projelerimizde kullanabilmek üzere http servisleri geliştirmemizi sağlayan, platformlar arası veri alışverişini sağlamak için kullanılan bir frameworktür. Asp.Net wep Api kullanarak farklı dillerde yazılmış olan uygulamalarımız web'in ortak kabul ettiği medya tiplerinde(XML, JSON) çıktıları vererek birbirleri ile veri alışverişinde bulunabilirler ve birbirlerine entegre sistemler olarak çalışabilirler. Asp .net Web Api, Asp .Net Core'un bir parçasıdır ve MVC veya diğer web application türleri ile birlikte kullanılabilir. Sonuç olarak Wep Apı; bizim diğer platformalar ile yada diğer teknolojiler ile haberleşmemizi sağlayan bir teknolojidir. Yani bizim Microsoft server üzerinde koşan bir uygulamamız ile apache server üzerinde koşan PHP tabanlı uygulamanın haberleşmesidir.
MVC dizayn pattern kalıbı uygulanmıştır. Asp .Net MVC içerisinde bizlere sunulan Routing, Controller, IActionResult gibi yapılar Asp.Net Wep API içerisinde bulabilirsiniz.
ÖRNEK 1 ; Paycell ödeme API’leri, üye işyerlerinin müşterilerine sunacağı önyüzleri üzerinden (web, application, vb) müşterinin Paycell’de tanımlı olan kartlarını ya da mobil ödeme yöntemini kullanarak ödeme işlemlerini gerçekleştirmelerini ve Paycell’deki ödeme yöntemlerinin yönetimini sağlayabildikleri (kart ekleme, silme, güncelleme, mobil ödeme açma) web servis arayüzlerini sağlamaktadır.
ÖRNEK 2; kurumlarda farklı teknolojilerle ve farklı fiziksel konumlarda barındırılan şirket içi yazılımlara tek kullanıcı adı ve tek şifre ile giriş yapılmasını sağlayan bir uygulama geliştireceğimizi düşünelim. Bu uygulama için kullanıcı doğrulama işlemini tek bir yerden yaptırıp dönen sonuç doğru ise ilgili uygulamada oturum açılabilmesi sağlanabilir. Kimlik doğrulama işlemi LDAP gibi bir ortamda yapılabilirken buraya yapılacak bağlantı API ile gerçekleştirilir ve diğer tüm uygulamalar Login işlemini doğrulamanın olduğu yerde yapmak için geliştirilen API’yi kullanır. API kullanımı oldukça yaygın ve çok geniş bir alana sahiptir fakat SSO benzeri bir uygulama ile basitçe ne şekilde kullanılabildiğine dikkat çekmek istedim.
Wep API kullanım alanlar;
Mobil uygulamalar,
SPA(Single PAge Aplication) Web siteleri
Entegrasyonlar
Bir uygulamamnın geliştiricilere açılması
Web Servise; Http protokolu üzerinden XML veya JSON medya tipleri ile uzak cihazlar arasındaki iletişimi sağlayan bir haberleşme yöntemidir. XML veya JSON meyda tiplerinde olması sayesinde platformlar arası ve programlama dilelri arasında haberleşme sağlanabilir.
Http protokolu; "Hyper TextTransfer Prorocol" yani "Hiper Metin Trasnfer Protokolu"dür. Http Protokolü ağ üzerinden web sayfalarının görüntülenmesini sağlayan protokoldür. Http Protokolü işlemci ile sunucu arasındaki alışveriş kullarını belirler.
REST(Representational State Transfer), 2000 yılında Roy Fielding tarafından doktora tezinde tanıtılmış ve tanımlanmıştır. REST, dağıtık sistemler tasarlamak için kullanılan bir mimari tarzdır.
REST, client-server arasındaki haberleşmeyi sağlayan HTTP protokolü üzerinden çalışan bir mimaridir. REST ,servis yönelimli mimari üzerine oluşturulan yazılımlarda kullanılan bir transfer yöntemidir. İstemci ve sunucu arasında XML ve JSON verilerini taşıyarak uygulamanın haberleşmesini sağlar. REST mimarisini kullanan servislere ise RESTful servis denir.
RESRful servisin taşıması gereken karakteristik prensipler;
Client-Server ; (istemci-sunucu) Client server hakkında Server client hakkında birşey bilmez.
Stateless; (durumsuz) Server tarafında client ile ilgili hiçbir bilgi tutulmaz. Client ile server arasında bir durum taşıma söz konusudur.
Cachebale;(önbellekte tutulabilir) Server tarafından response(tepki) de cache'lenebilirliği gönderilir ve client veriyi cache'leyebilir. Bu durumda client ister cache'leyebilir ister cache'lemez. Ayrıca reesponse header'da cachelenebilirlik ve expire(süre dolama zamanı vs) bilgileri bulunur. Client bu bilgiler ışında kendisine aldığı bilgileri yani veriyi belirli bir süre kendi içeresinde tutabilir. Server gitme ihtiyacı duymayabilir ve o süre geldiğinde servise yine request atarak elindeki bilgiyi güncelleyebilir.
Uniform Interface; client ile server arasında ortak bir URL formatında arayüz bulunması. Aslında URL üzerinden ilgili arayüzleri, programatik işlemlere erişebilmesi durumudur.
Code on Demand; Bazı durumlarda response olarak Client-Side Script göndermesi durumudur. Buda işlevselliği ve performansı arttırmak adına uyulması gereken bir prensip olarak gösterilmektedir. Lakin opsiyoneldir. Yapılmasada olur. Bazı sitelere request atıldığında o siteler bizim bilgisayarımızda bir uygulama açma isteği örnek olarak verilebilir.
GET; laynağı url üzeriden erişmek için kullanılan http Method'tur.GET request’ler güvenli ve idempotent olmalıdır, yani aynı parametrelerle kaç kez tekrar ettiğine bakılmaksızın sonuçlar aynıdır.GET ile veri gönderilirken ,adres çubuğunda gönderilir.Gönderilen değişkenler ve veriler adres çubuğunda görüntülendiği için güvenilir değildir. Örneğin: Get ile sipariş detaylarını getirebiliriz. GET : /orders/{id}
POST; işlenecek verileri belirli bir kaynak URL göndermemizi sağlar. Şuan sunucuda bulunmayan ilk defa işlenecek veriler için tercih edilir. Örneğin: POST ile yeni bir sipariş oluştururuz. POST: /orders/
PUT; Belirtilen kaynak URL de işlenecek olan verilerin yüklemesini sağlar. Veri güncelleme işlemlerinde tercih edilir. Post'a göre daha performanslı çalışır. PUT ‘un POST’dan farkı idempotent olmasıdır.Yani bir request birden fazla kez tekrarlansa da sonucunun aynı olmasıdır. Örneğin: PUT ile belirli sipariş güncelleriz. PUT : /orders/{id}
PACH; Verinin sadece bir parçasını güncellemek için kullanılır.
HEAD; Get isteğine benzer fakat, sadece istek ile ilgili veya cevap ile ilgili bilgiler head istediğinde taşınır.
OPTİONS; sunucunun desteklediği HTTP METHOD'larını döndürür.
CONNECTS: TCP/IP kanalı üzerinden sunucu ile istemci arasındaki açılan bağklantı bilgisini döndürür.
HTTP status codes
1XX ile başlayan kodlar bilgi amaçlı kodlardır.
2XX ile başlayan kodlar başarı kodlarıdır.
3XX ile başlayan kodlar yönlendirme kodlarıdır.
4XX ile başlayan kodlar ise client(istemci) hatası kodlarıdır.
5XX ile başlayan kodlar ise server(sunucu) hatası kodlarıdır.
Web uygulamalarının birbirleri ile konuşmaları için kaynak paylaşımları yapmaları gerekir. Kaynak paylaşımı yaparken ;
Hangi domainlerin bu kaynağa erişebileceğini,
Hangi methodların hizmet vereceğini,
Hangi medya tipinde veri çıkışına izin vereceği gibi kıstaslar tutulur.
Aynı domainde olan uygulamalar için kaynak paylaşımında özel bir konfigurasyona gerek yoktur. Bu duruma Same Origin denir. Ama Domainler farklı ise configurasyona gerek duyulur.
sunucuda bulunan bir kaynağa yetkisiz erişimi engellemek amacı ile sunucu tarafından belli süreliğine oluşturulmuş hashlenmiş bir kod olarak authentication sürecinden sonra istemciye gönderilen ve kullanıcının sunucudaki tüm kaynak erişimlerine bu erişim bileti (access-token) ile erişebilmesini sağlayan dağıtık mimarilerde tercih edilen bir güvenlik yöntemidir.
Access token; kullanıcının access token üzerinden hangi clientlara ulaşılması gerektiği sunucuya tanıtılarak, her bir access token üzerinden kaynak erişimlerinde kimlik doğrulayan kullanıcının bilgileri üzerinden kaynak yapmamızı sağlar. Kullanıcı sunucundan yeni bir erişim bileti talep edene kadar, kaynak erişimleri bu access token ile yürütülecektir.
Kullanıcı; kullanıcı adı ve şifre bilgilerini sunucuda tanımlanmış bir token endpoint'e gönderir. Eğer kullanıcı hesabı sistemde tanımlanan bir kullanıcı ise WebApi kullanıcı bilgilerine göre kullanıcının talep edilecek olan claimslerini oluşturur. Tüm yetkilendirme süreçleri bu claimsler üzerinden kontrol edilecektir. Daha sonra claimsler ClaimsIdentity olarak sunucuya tanıtılarak oturum açmış olan kullanıcı işin api tarafından kaynak erişim bileti access token gönderilir.
Api ile haberleşen Web-client tarafından access token, cookie, local veya session storage gibi client taraflı veri saklama yöntemleri kullanılarak sunucudan gönderilen bilgileri doğrultusunda yaşam süresi kadar oluşturulmuştur. Kullanıcı sunucu ile olan tüm bu iletişim access token ile gerçekleştirir.
Eğer istemci oturumunu kapatamakl istiyor ise access token client tarafından silinir ve kullanıcı tekrar Api den access token almak için login sayfasına yönlendirilir.
Eğer http protokolü üzerinden web sunucusuna gelen istek de access token yok ise sunucu istemciye An Authorize 401 HttpStgatusCode ile dönüş yapar. Tabi burada dikkat edilmesi gereken nokta kaynağa erişilmesi gereken endpointlerin üzerinde [Authorize] attribute kullanılmalıdır.
Bunun dışında Web APi tafaında token Based Authentication yapısını AuthenticationMode.Bearar ile yapmaktayız.
OpenAPI, iki bilgisayar sisteminin birbirleriyle haberleşebilmesi amacıyla oluşturulmuş bir standarttır. Fakat bu apilerin belirli bir standart biçimi olmadığı için, herkesin üzerinde anlaştığı standart bir servis sözleşme biçimi yok ve bu durum çokta istenilen bir durum değildir. Fakat Swagger OpenAPI, standardını kullanarak, API’lerimizi hem insanların hem de makinelerin anlayacağı formatta ortak bir dilde paylaşabiliyor. İnsanlar Open API sözleşmelerinize bakınca servis içeriğinin ne olduğunu anlayabilir. Bunun yanında makineler için sözleşme kurallarına uyan client veya server kodu üretebiliriz.
Swashbuckle, Swagger tanımı oluşturan bir kütüphane olarak tanımlayabiliriz.
Swagger: eliştiriciler için RestFul web hizmetlerini tasarlamasına, oluşturmasına, belgelemesine yardımcı olan bir araçtır. Geniş bir ekosistem tarafından desteklenen açık kaynak bir uazılım framework'tür. Swagger üç ana alanda geliştiricilere yardımcı olur. Bunlar:
API Geliştirme : API oluşturulurken, Swager aracı kodun kendisine göre otomatik bir açık API belgesi oluşturmak için kullanılıyor. Bu Apı açıklaması bir projenin kaynak koduna gömülür. Alternatif olarak Swagger Codegen kullanılarak geliştiriciler kaynak kodun Open API belgesinden ayırabilir ve doğrudan istemci kodu ve dokumantasyonu oluşturulabilir.
API'lerle Etkileşim Kurma: Swagger Codegen projesini kullanarak son kullanıcılar istemci SDK'larını doğrudan Open Apı belgelsinden oluşturur ve istemci tarafından gelen yada oluşturulan istemci kodu gereksinimleri azaltırılır.
API'ler İçin Dokümantasyon: Bir API için OpenApı belgesi tanımlandığındai Swagger açık kaynak aracı,i Swagger kullanıcı arayüzü üzerinden API ile doğrudan etkileşim kurmak için kullanılır. Html tabanlı bir kullanıcı arabirimi aracılığı iloe doğudan canlı API'lere bağlantı kurulmasını sağlar. Client istekleri doğrudan Swagger UI üzerinden gerçekeştirebilir.
Swagger Aracını Nuget Package Manager yada GitHub üzerinden erişebilir ve projenize entegre edebilirilsniz. Github Link: https://github.com/swagger-api/swagger-ui Nuget Package Name: Swashbuckle.AspNetCore Doc: https://docs.microsoft.com/en-us/aspnet/core/tutorials/getting-started-with-swashbuckle?view=aspnetcore-3.1&tabs=visual-studio
Swagger, geliştiricilerin RESTful web hizmetlerini tasarlamasına, oluşturmasına, belgelemesine ve tüketmesine yardımcı olan geniş bir araç ekosistemi tarafından desteklenen açık kaynaklı bir yazılım çerçevesidir. ( https://coskunkurtuldu.medium.com/swashbuckle-ve-asp-net-core-54a60a47b909 )
