Burak Selim Şenyurt | Nasıl bir Web API Tasarımı?
← FizzBuzz ile Basit Bir TDD Pratiği
Post Görünümlü Put →
Web API'ler ya da RESTful API türünden servisler çok uzun zamandır hayatımızda. Benim de gerek blog yazılarımdaki örnekler olsun gerek iş yerinde kullandıklarımız olsun sürekli haşırneşir olduğum enstrümanlardan birisi. Ancak son zamanlarda okuduğum kaynaklardan sonra bir çok tasarım hatası yaptığımı ve uygulamadığım şeyler olduğunu fark ettim. Nedir bu işin doğru yolu diyerek ortak standartları araştırmaya başladım. Elde ettiğim bir takım sonuçlar oldu. Bu sonuçlardan basit bir çizelge de hazırladım. Aşağıda görebilirsiniz. Ama öncesinde bir kaç kısa bilgi verelim.
Bu tip servisler çoğunlukla kaynaklarla(resources) ilgili temel işlemleri gerçekleştirmek için kullanılmakta. Kaynakların listelenmesi, eklenmesi, silinmesi veya güncellenmesi söz konusu temel operasyonlar olarak düşünülebilir. Servisler, kaynaklarla ilgili operasyonları belli adresler(endpoint diyebiliriz) üzerinden sunar. Servislerin, sundukları kaynakların ve endpoint'lerin sayısı arttıkça baştan düşünülmesi gereken standartlar olduğunu fark ederiz. Özellikle bu servisler farklı takımlarca geliştiriliyorsa. Bu noktada kaynakların isimlendirilmesinden servis adresinin nasıl olacağına, versiyon bilgisinden serileştirme formatının bildirimine, operasyon adlarından döndürülecek HTTP cevaplarından istemciden hangi metodlarla gelineceğine kadar bir çok farklı kavram karşımıza çıkıyor. Bu konulardan bir kısmı ile ilgili olarak şunları söyleyebiliriz.
İsimlendirme standardı olarak aşağıdaki gibi kullanımlar öneriliyor.
İki kullanımdan birisi tercih edilebilir ama benim önerdiğim ikincisi. Dikkat edileceği üzere her iki tanımlamada versiyonlama bilgisi içermekte. Bazı kaynaklar versiyon bilgisinin Header içerisinde gönderilebileceğini de dile getiriyor ancak yukarıdaki yazımda olduğu gibi açık olması daha doğru.
HTTP Header kısmında daha çok istemci ve sunucu arasındaki mesajlaşmanın formatı belirtiliyor. Content-type ile request, Accept ile de response formatlarını belirtmemiz mümkün.
Diğer yandan sadece HTTP-Post ve Get desteği olan istemciler için mutlak suretle X-HTTP-Method-Override kullanılması bekleniyor. Bu konu ile ilgili şu yazıma bakabilirsiniz.
Resource isimlendirmelerinde de çoğul ifadelerin kullanılması öneriliyor. Yani category yerine categories şeklinde tanımlama yapmak lazım. Diğer kullanım önerilerini de şu şekilde özetleyebiliriz(Excel dosyasını indirmek için tıklayın)
Artık elimde/elinizde RESTful API tasarlamak için güzel bir kılavuz var. Bir başka yazıda görüşmek dileğiyle hepinize mutlu günler dilerim.
Etiketler : web api, asp.net web api, restful, rest based services, http, post, put, get, delete, service, standarts
Tam ihtiyacım olan zamanda böyle bir yazı. İnanılmaz güzel tesadüf oldu benim için. Teşekkürler.
06 Ağustos 2018 - Yanıtla
İşe yaramasına çok sevindim. Ben teşekkür ederim.
22 Ağustos 2018 - Yanıtla
17 Ağustos 2018 - Yanıtla
HEAD : Kodu XYZ olan ürün var mı?
PATCH : Kodu XYZ olan ürünü güncelle (PUT'dan farklı olarak sadece değişecek nitelikler gönderilir)
HTTP 409 (Conflict) : POST'a yanıt olarak ilgili kodda bir ürün zaten varsa dönülebilir.
Bu yazıdan sonra HATEOAS Driven API yazısı yakışır.
20 Ağustos 2018 - Yanıtla
Harika ipuçları ve bilgiler oldu bunlar, çok teşekkürler. HATEOAS Driven API konusuna bakacağım vakit bulabilirsem.
Üstadım çok güzel bir ROA yazısı olmuş eline sağlık.
Body, çok teşekkür ediyorum Bilgilendirici olmasına sevindim.