Rest Api Design Standartları

Rest ve restful karıştırılan genellikle de birbirinin yerine kullanılan kavramlar ancak temelde farklı kavramlardır. Rest, client-server arasındaki iletişimin HTTP protokolü sayesinde kolay ve hafif bir şekilde yapılmasını sağlayan bir mimaridir. Rest mimarisinde SOAP’da bulunan GetProduct , GetCategory gibi metotlar üzerinden iletişim kurulması yerine tüm bilgiler, URI’ler üzerinden sunulur.

Örn :  http://myserver/api/v1/products/1   gibi web linkleri düşünebiliriz.

Restful web servisleri ise , REST mimarisi temel alınarak geliştirilmiş oldukça hafif, genişletilebilir ve basit servislerdir.

REST STANDARTLARI

Rest standartlarıyla ilgili detaylı yazıma buradan Rest Standartları ulaşabilirsiniz. 

Resource Kavramı

Restful standartlarından bahsetmeden önce resource kavramından bahsetmek yerinde olacaktır. Restful servislerde “resource” (kaynak) kavramı, sunulan veri veya bilgi kaynaklarını temsil eder. Bu kaynaklar genellikle URL’ler aracılığıyla erişilebilir ve çeşitli HTTP metodlarıyla (GET, POST, PUT, DELETE vb.) yönetilir. Örneğin bir e ticaret uygulamanız var ise, bu uygulamada product, client ve order sizin resourcelarınız olabilir ve URI’ler üzerinden buna erişebilir ve HTTP metotlarıyla bu resource’lar üzerinde güncelleme yapabilirsiniz.

URL ve URI

URI, bir kaynağın benzersiz bir şekilde tanımlanmasını sağlar. URL ise, bu kaynağın nerede bulunabileceğini belirtir. Yani, URI bir konseptin genel adıdır ve URL, bu kavramın bir alt kümesidir.

Örneğin, “https://www.example.com/page” bir URL ve aynı zamanda bir URI’dir. Çünkü bu, belirli bir kaynağın yerini (web sayfasını) belirtir.

Ancak, “mailto:user@example.com” sadece bir URI’dir, çünkü bir e-posta adresini tanımlar, ancak bu URI bir URL değildir çünkü belirli bir kaynağın konumunu belirtmez, sadece bir eylemi (e-posta gönderme) tanımlar.

Kısacası, URI her şeyi kapsar, URL ise belirli kaynakların yerlerini tanımlayan bir türdür.

Bir API yaparken aynı sınıfa ait işlemleri bir grup altına toplamalıyız. Örneğin API üzerinden kullanıcılara ait erişmek ve işlem yapmak istediğimizde hepsini “Users” url’i üzerinden yapmalıyız.

RESTFUL STANDARTLARI ve BEST PRACTICELER

1. Resource İsimlendirmesi

Resource ismi çoğul olarak isimlendirilmelidir. Bunun sebepleri ise

  1. Tekil ve Çoğul Kavramları Arasındaki Tutarsızlık: Bir RESTful API’de, genellikle birden fazla öğe veya kaynak bir arada ele alınır. Örneğin, bir kitap mağazası uygulamasında, “kitaplar” kaynağı “kitap” kaynağının bir koleksiyonunu temsil eder. Dolayısıyla, resource’ın ismi bu koleksiyonu yansıtmalı ve “books” gibi çoğul bir isim kullanılmalıdır.
  2. URL Yapısının Tutarsızlığını Azaltma: Çoğul isimler kullanılarak controller’ların isimlendirilmesi, URL yapısını tutarlı kılar. Örneğin, “/books” URL’si “kitaplar” kaynağına işaret ederken, “/book” URL’si tek bir “kitap” kaynağına işaret eder. Bu tutarlılık, API kullanıcılarının ve geliştiricilerin API’yi daha kolay anlamasına ve kullanmasına yardımcı olur.

2. HTTP Metotları

        – GET metodu

Eğer Get Http metodu ile tüm productları listelemek istiyorsak bu noktada urimizin bir parametre almamalıdır. Aşağıdaki structure’a uyması gerekir.

.../products

Ancak specifik bir productı çekmek istiyorsak aşağıdaki gibi query parammıydı neydi bu structureda olmalıdır.

.../products/{product_id}

– POST metodu

Post metodu ise yeni bir resource yaratmak için kullanılan HTTP metodudur. Yaratacağı resource’ı body’den almalı ve takip etmesi gereken URI structureı aşağıdaki gibi olmalıdı.
.../products

– PUT metodu

Put metodu ise full update yani replace için kullanılan HTTP metodudur. Dolayısıyla URI üzerinde replace edeceği productin IDsini alması yeterlidir. Replace edilecek resource’ı bodyden almalı ve aşağıdaki structure’ı takip etmelidir.
.../products/{product_id}

– DELETE metodu

Delete http metodu ise adından da anlaşılacağı üzere bir resource’ı silmeye yarayan HTTP metodudur. Dolayısıyla URI’de hangi resource’ı sileceğinin ID’sini alması yeterlidir.

..../products/{product_id}

3. Hiyerarşik URI

Bir resource grubuna ait bağlantılı başka bir resource grubuna ulaşmak istiyorsak örneğin bir orderin productları gibi, aşağıdaki structucture’ı takip etmeliyiz
/orders/{order_id}/products
 4. Url oluşturulurken fiil değil isim kullanılmalıdır. Çünkü rest apiler dışarıya fonksiyonlarını açmaz. Fonksiyonlar urinin arkasında gizlidir ve yapılan şey resourceları yönetmektir. Ayrıca HTTP protokolü, bir kaynağın üzerinde yapılacak işlemleri belirlemek için çeşitli yöntemler (GET, POST, PUT, DELETE vb.) sağlar. Bu yöntemler zaten fiil eylemlerini ifade ederler. Dolayısıyla, HTTP yöntemlerini kullanarak kaynakları işaret etmek ve işlemleri gerçekleştirmek, RESTful API’nin doğal yapısına uygun olur.
/createTeam X
/getTeams X
/update/teams/97  x
POST /teams Yeni takım oluşturmak için uygulanabilir.
GET  /teams  Mevcut tüm takımları getirmek için uygulanabilir.

5. İstekten etkilenen kişi ID’si ile url’e PathVariable olarak eklenmelidir.

GET  /teams/97  97 ID'li takımın bilgileri için uygulanabilir.
PUT  /teams/97  97 ID'li takımı güncellemek için uygulanabilir.
DELETE /teams/97  97 ID'li takımı silmek için uygulanabilir.


6. Filtreli Sorgular

Çoğu zaman, belirli bir kaynak özelliğine göre sıralanmış, filtrelenmiş veya sınırlandırılmış bir kaynak koleksiyonuna ihtiyaç duyacağınız gereksinimlerle karşılaşırsınız. Bu gereksinim için yeni API’ler oluşturmayın; bunun yerine var olan API’de sıralama, filtreleme ve sayfalandırma özelliklerini etkinleştirin ve giriş parametrelerini sorgu parametreleri olarak iletin. Örneğin,

/device-management/managed-devices 
/device-management/managed-devices?region=USA 
/device-management/managed-devices?region=USA&brand=XYZ 
/device-management/managed-devices?region=USA&brand=XYZ&sort=installation-date

7. Okunabilirlik açısından birden fazla kelimeler ayrılmalı, alt çizgi ve büyük harf tercih edilmemeli, sonda eğik çizgi olmamalı ve kısaltmalar tercih edilmemelidir.

HTTP GET /device-management/managed-devices/{id} 

HTTP Hata Kodları

• 1xx – Bilgi Mesajları

• 2xx – Başarılı Mesajları

• 3xx – Yönlendirme Mesajları

• 4xx – Client(istekte bulunan cihaz/kişi) Hata Mesajları

• 5xx – Sunucu(server) Hata Mesajları

Faydalı linkler

https://restfulapi.net/resource-naming/

https://restfulapi.net/rest-architectural-constraints/

https://caylakyazilimci.com/post/restful-api-nedir-ve-standartlari-nelerdir

https://medium.com/devopsturkiye/rest-nedir-isimlendirme-standartlari-nelerdir-d91893b9388

You may also like...

Bir Cevap Yazın

E-posta hesabınız yayımlanmayacak. Gerekli alanlar * ile işaretlenmişlerdir