.NET Core REST

Paylaş

.NET Core ile REST tabanlı web servis hazırlarken dikkat edilmesi gerekenler ve hazırladıktan sonra yapılması gerekenlerle ilgili bilgiler yer alıyor.

REST nedir?

REST ile ilgili detaylı bilgi için REST Nedir? yazıma bakmalısın.

REST tabanlı web servis hazırlarken herhangi bir sınırlama veya kural yoktur.

Ancak sıklıkla kullanılan ve kalıplaşmış(best practices) yapıların kullanımı iyi bir REST API için faydalı olacaktır.

1.Planlama

REST tabanlı bir web servis hazırlarken ilk olarak API içinde yer alacak işlevlerin belirlenmesi faydalı olacaktır.

Bu adımda REST API hangi amaçla kullanılacak, hangi işlevlere sahip olacak gibi web servis kapsamı belirlenir.

2.Dosya ve dizin yapısı

API ile ilgili kapsam belirlendikten sonra iyi bir dosya ve dizin yapısının oluşturulması geliştirme ve tekrar kullanılabilirlik için faydalı olacaktır.

Dosya ve dizin yapısını kendimiz oluşturabileceğimiz gibi .NET CLI aracıyla oluşturabiliriz.

dotnet new webapi

.NET Core ile proje geliştiriken katmanlı mimari(n-tier), Onion, Hexagon, MVC gibi çeşitli mimariler kullanılabilir.

Burada dikkat edilmesi gereken geliştirme yaparken Sorumlulukların Ayrılması(SOC) prensibine uyulmasıdır.

Dosya ve dizin yapısını hazırlarken her bir katmanın kendi işini yapması test, genişletilebilirlik ve tekrar kullanılabilirlik gibi işlemler için faydalı olacaktır.

NOT: .NET Core varsayılan olarak MVC mimarisini kullanır.

3.Ayarların yapılması

.NET Core ile REST API hazırlarken API ayarlarının iyi hazırlanması oluşabilecek sorunları önlemek ve tekrar kullanılabilirlik için faydalı olacaktır.

.NET CLI ile proje oluşturulduğunda varsayılan olarak ayarların yapıldığı Startup.cs dosyası oluşturulacaktır.

Dosya içerisindeki ConfigureServices metodu ile kullanılacak servisler projeye dahil edilir.

Örneğin; ASP.NET Core MVC servisini projede eklemek için AddMvc metodu kullanılır.

services.AddMvc();

.NET 5+ karşılığı aşağıdaki gibidir.

builder.Services.AddControllersWithViews(); // .NET 5 +

Servis projeye eklendikten sonra Configure metodu ile ayarları yapılır.

Örneğin yukarıda eklediğimiz MVC özelliğini kullanmak için Configure metoduna aşağıdaki komutu eklemek yeterli olacaktır.

app.UseMvc();

.NET 5+ karşılığı aşağıdaki gibidir.

app.UseRouting();

Başka bir adresten bir istek geldiğinde güncel tarayıcılar bunu CORS olarak adlandırılan kural gereği engelleyecektir.

CORS yapısına izin vermek için aşağıdaki komut ConfigureServices metoduna eklenir.

services.AddCors();

.NET 5+ karşılığı aşağıdaki gibidir.

builder.Services.AddCors(); // .NET 5+

CORS servisi projeye eklendikten sonra Configure ile ayarları yapılır.

app.UseCors(builder => builder
    .AllowAnyOrigin()
    .AllowAnyMethod()
    .AllowAnyHeader()
    .AllowCredentials());

.NET Core ile servis ekleme ve ayarlarının yapılması kolay olsa da ayar sayısı arttıkça Startup.cs dosyası gereğinden fazla genişleyebilir.

Bu sorunun önüne geçebilmek için C# Extension Method özelliği ile IServiceCollection arayüzüne çeşitli eklemeler yapılabilir.

Dosya ve dizin yapısı ile ayarlar iyi hazırlanırsa bu yapı daha sonra başka bir web servis hazırlarken de kullanılabilir.

ASP.NET Core hakkında detaylı bilgi için ASP.NET Core yazıma bakmalısın.

4.Adlandırma

Daha anlaşılır bir REST API yapısı için adlandırma olarak çoğul adların kullanımı faydalı olacaktır.

// İyi
/api/musteriler:     Tüm müşterileri getir.
/api/musteriler/25:  Sıra numarası 25 olan müşteriyi getir.

// Kötü
/api/musteri:     Tüm müşterileri getir.
/api/musteri/25:  Sıra numarası 25 olan müşteriyi getir.

// Kötü - işlem ile ilgili bilgi veriyor.
/api/musterilerigetir
/api/musterilerigetir/25

NOT: Adlandırma sırasında işlem ile ilgili bilgi vermek(musterilerigetir, musterisil, musteriguncelle) hazırlanan web servisin karmaşık olmasına neden olacaktır.

NOT2: .NET Core adlandırma veya Routing işlemi sırasında Attribute Routing özelliğini kullanmak geliştirilen REST API yapısının daha anlaşılır olmasını sağlar.

5.HTTP yöntemleri

Adlandırma sırasında işlem ile ilgili bilgi vermek yerine HTTP protokolünde yer alan HTTP yöntemleri kullanılır.

Aşağıdaki HTTP yöntemleri yaygın olarak REST tabanlı mimaride kullanılır.

GET – Veri almak için kullanılır.
PUT – Veri üzerinde değişiklik yapmak için kullanılır.
DELETE – Veri silmek için kullanılır.
POST – Veri göndermek/eklemek için kullanılır.

HTTP yöntemlerinin kullanımı hazırlanan web servis yapısını daha anlaşılır kılacaktır.

// İyi
GET    /api/musteriler
POST   /api/musteriler
PUT    /api/musteriler/:id
DELETE /api/musteriler/:id

// Kötü - Her bir işlem için ayrı tanımlama yapılmış.
/api/musterilerigetir
/api/musterilerigetir/:id
/api/musteriguncelle/:id
/api/musterisil/:id

.NET Core ile REST API hazırlarken HTTP yöntemlerini belirtmek için HttpGet, HttpPost, HttpPut, HttpDelete nitelikleri kullanılabilir.

6.HTTP durum kodları

İşlem sonucu ile ilgili bilgi vermek için HTTP protokolünde yer alan HTTP durum kodları kullanılır.

Aşağıdaki HTTP durum kodları yaygın olarak REST tabanlı mimaride kullanılır.

200 OK – İşlem başarıyla gerçekleşirse kullanılır.
201 CREATED – İşlemi başarıyla gerçekleşirse kullanılır. Eklenen veri döndürülür.
204 NO CONTENT – İşlemi başarıyla gerçekleşirse kullanılır. Eklenen, silinen veri döndürülmez.
400 BAD REQUEST – Hatalı istek veya yetkilendirme hatası için kullanılır.
401 UNAUTHORIZED – Yetkilendirme hatası için kullanılır.
403 FORBIDDEN – Yetkilendirme ve erişim hatası için kullanılır.
404 NOT FOUND – İstenilen işlem yoksa kullanılır.
405 METHOD NOT ALLOWED – İzin verilmeyen HTTP yöntemi kullanıldığında bilgi vermek için kullanılır.
409 CONFLICT – Aynı veri üzerinde birden fazla kişinin işlem yaptığını bildirmek için kullanılır.
500 INTERNAL SERVER ERROR – Sunucuda herhangi bir hata olduğunda kullanılır.

Her istek sonucunda 200 durum kodunu göndermek yerine işlem sonucuna göre ilgili işlem kodunu kullanmak faydalı olacaktır.

.NET Core durum kodlarını bildirmek için Ok, NotFound, BadRequest, NoContent, Created, CreatedAtRoute, CreatedAtAction, Unauthorized, Forbid ve StatusCode metotları kullanılabilir.

7.API sürümü

Geliştirilen REST API başka kullanıcı ve firma(lar) tarafından kullanılacaksa API sürümü kullanmak faydalı olacaktır.

/api/v1/musteriler/:id

REST API’de yapılan kapsamlı değişiklik sonrası sadece API sürümünün değiştirilmesi yeterli olacaktır.

/api/v1/musteriler/:id

API sürümünün verilmesi dokümantasyon ve iyi bir REST API yapısı için gereklidir.

8.Sorgu kullanımı

Geliştirilen API içinde yer alan verileri alırken çeşitli sorgu parametrelerin kullanımı esneklik ve trafik açısından faydalı olacaktır.

// Tüm müşterileri getir.
/api/v1/musteriler

// Tüm müşterileri name alanına göre sıralanmış olarak getir.
/api/v1/musteriler?sort=name&direction=asc

// Müşteriler alanında name alan değeri Yusuf olan müşterileri getir.
/api/v1/musteriler?name=Yusuf

// İlk 30 müşteriyi name alanına göre sıralanmış olarak getir.
/api/v1/musteriler?sort=name&direction=asc&limit=30

// Sıralanan müşterilerden 30 ila 60 arasındakileri getir.
/api/v1/musteriler?sort=name&direction=asc&limit=30&offset=30

Sorgu kullanımı sırasında varsayılan değer vermek gereksiz trafik kullanımını önleyecektir.

Örneğin; 10 bin müşteri kaydı varsa hepsini vermek yerine 100 tane kayıt vermek ve diğer kayıtlara limit, offset veya sayfa numarası gibi sorgu parametreleriyle erişmek faydalı olacaktır.

Ayrıca daha fazla ve daha gelişmiş sorgulama için GraphQL gibi tekniklerde kullanılabilir.

9.Test

REST API geliştirirken ve geliştirdikten sonra performans, hata ve sorunlara karşı test edilmesi faydalı olacaktır.

Test işlemi için tarayıcı veya işletim sisteminde yer alan komutlar kullanılabileceği gibi Postman, Insomnia, Paw ve SOAPUI gibi araçlarda kullanılabilir.

10.Dokümantasyon

REST tabanlı web servisler için WSDL gibi bir tanımlama ve açıklama standardı olmadığından dolayı geliştirilen REST API kara kutu olacaktır.

Geliştirilen REST API web servisinin anlaşılabilir olması için apiDoc, Swagger, API Blueprint gibi araçlar kullanılarak kullanım dokümanının hazırlanması faydalı olacaktır.

.NET 5+ şablonunda varsayılan olarak gelen Swagger hakkında detaylı bilgi almak için .NET Core Swagger yazıma bakabilirsiniz.

.NET Derslerine buradan ulaşabilirsiniz.

Hayırlı günler dilerim.

Facebook