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
- 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.
- 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
.../products
– PUT metodu
.../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
/orders/{order_id}/products
/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
