REST API, REST mimarisine uygun oluşturulan HTTP API servislerdir. Rest API için resmi olmayan RESTful teriminin kullanıldığını da görebilirsiniz. Peki ama REST API nedir? İşte bilinmesi gerekenler ve merak edilenler…
REST API’yi daha doğru anlamak ve kavramak için öncelikle REST’i sonrasında ise API’yi anlamak gerekir, eğer öğrenmek ya da bildiklerinizi tazelemek isterseniz REST Nedir? ve API Nedir? içerikleri sizin için faydalı olacaktır.
REST API servisleri için başlangıçta bir kural seti yoktu fakat, uzun yıllardır kullanılmış olması nedeniyle zaman içerisinde edinilen tecrübeler sayesinde best-practices (en iyi uygulamalar) ve bazı standartlar (bkz: OpenAPI) doğmuştur. Makale devamındaki bir çok bilgi günümüzde kabul görmüş ve REST API için sektör standardı haline gelmiş konuları içermektedir.
Günümüzde REST API yerine geçmesi üzerine yine zaman ve gereksinimler içerisinde doğmuş GraphQL ve RPC varken REST API ile ilgili çok kapsamlı bir makale yazmak geleceğe faydası düşünüldüğünde verimsiz olabilir. Hali hazırda REST API ile ilgili binlerce makale bulunduğundan daha ayrıntılı bilgi edinmek isterseniz geçmişte yazılmış makaleleri incelemenizi tavsiye edebilirim. O halde haydi başlayalım;
Bir HTTP API servis ile ilgili ilk belirlenmesi gereken şey URI yapısıdır. Routing (yönlendirme) değişikliği servisin aktif kullanıcı sayısı arttıkça hem geliştiren hem de mevcutta entegre sağlamış paydaşlar için sancılı bir konu olacağından yapının başında doğru bir şekilde belirlenmesi gelecekte yaşanabilecek olası sancıların önüne geçecektir.
{protocol}://{domain}:{?port}/{basePath}/{area}/{?version}/{endpoint}
protocol: http ya da https olabilir.
domain: servisin bulunduğu genellikle alt alan adlarının olduğu kısımdır. (Ve ortama göre değişiklik gösterebilir. örn: uat.my-service.com, staging.my-service.com)
?port: Standart 80 ve 443 dışında bir port kullanımı söz konusu ile ayrıca belirtilmesi gerekir fakat standart portlar için zaten protocol üzerinden bu port bilgisi anlaşılır.
basePath: Bu kısım genellikle api olur fakat aynı domain altında birden fazla servis bulunması halinde catalog-api, cart-api gibi alt servis isimleride olabilmektedir.
area: Servisin altındaki modül ya da alt servis adı olabilmektedir. (örn: basePath api ise area olarak mobile, basePath catalog-api ise area olarak product)
?version: sürüm yönetimi için kullanılır fakat URI içerisinde yer almadığı, header ile belirtilebildiği hatta istemci tarafından belirtilmesi istenmiyorsa yalnızca server tarafından belirlediği bir yapıda mümkün. Buradaki versiyonlamada anlamsal versiyonlama (semantic versioning) kullanabilir ya da YYYY-MM gibi kendimizin anlamlandırdığı sürümler oluşturabiliriz.
Hatta hiç sürüm yönetimi desteği bulunmayabilir fakat bu önerilmez çünkü serviste bir güncelleme gerektiğinde sürüm yönetim alt yapısı yoksa sürekli olarak geriye uyumluluk (backward compatibility) endişelerimiz ve bu endişeye bağlı ek maliyetler/sorunlar ile uğraşmamız gerekir.
{endpoint}: Bu kısımda ise servis uç noktası (service endpoint) dediğimiz URI’lerimiz olacak.
URI yapısı ile ilgili temelleri anladıktan sonra artık geliştirici olarak bizi daha yakından ilgilendiren endpoint kısmını yakından inceleyebiliriz. Öncelikle bilmeliyiz ki HTTP metodları ve HTTP durum kodları REST API servislerde çok büyük önem ve anlam taşımaktadır. Öncelikle HTTP metodlarının servislerdeki anlam ve yeteneklerini anlayalım;
GET – Okuma
Bir API endpoint (API uç noktası) GET ile istek kabul ediyorsa bu uç noktayı kullanarak veri okunabileceğini anlayabiliriz. İstek gövdesinde (request-body) bir şey bulunamayacağı, veri değişimine sebep olmaması gerektiği vs. detayları bulunmaktadır.
POST – Oluşturma
Yeni bir kayıt oluşturmak için kullanılır.
PUT – Güncelleme
Mevcut bir kaydın tüm alanlarını içerecek şekilde güncellemek için kullanılır.
PATCH – Kısmi Güncelleme
Mevcut bir kaydın bazı alanlarını güncellemek için kullanılır.
DELETE – Silme
Mevcut bir kaydı geçici ya da kalıcı olarak silmek için kullanılır. RFC 7231 içerisinde DELETE isteklerde gövde olmaması gerektiğine dair bir ifade olmasa da bazı frameworkler vs. DELETE istekleri için gövde ayrıştırması ya da erişimi desteklemiyor olabilir. (Ama olmasının faydalarını çokça görmüş birisi olarak, standartlar tarafında da buna engel bir husus bulunmadığından kullanılmasını tavsiye edebilirim.)
Her servis tekil ya da çoğul işlem yapabilir. (örn: GET servisinde URI’mız /products/1 ise yalnızca 1 ID’li ürün bilgilerini dönebilir, /products içerisinde de liste dönebiliriz. Aynı örneği toplu ekleme/güncelleme/silme içinde düşünebilirsiniz.)
Örneğin; [GET] uat.my-company.com/api/catalog/v1/products servisinin ürün listesi döndüğünü anlarken [GET] uat.my-company.com/api/catalog/v1/products/{id} servisinin yalnızca ileteceğimiz ID’ye ait tek ürün bilgisi döndüğünü anlayabiliriz.
HTTP durum kodlarına gelecek olursak aslında REST’e özel durum kodları uygulandığı bir durum genellikle (özel mikro servis ağları gibi extreme kullanımları düşünmezsek) yoktur. Bu kapsamda developer.mozilla.org/en-US/docs/Web/HTTP/Status üzerindeki durum kodlarını incelemeniz faydalı olacaktır. Ama çok kısa bir kaç örnek vermek gerekirse;
200: Başarı ile sonuçlanan herhangi bir isteğin yanıtında
400: İsteğin geçersiz olduğu (zorunlu alanların gönderilmemesi ya da verilerin olması gerektiği gibi olmadığı durumlarda)
401: İsteği atmaya yetkili olmadığımız ya da kullanıcı bilgisinin geçerli olmadığında
alacağımız ya da dönmemiz gereken durum kodlarıdır. REST API servislerde bir POST request sonucunda 200 vermek yerine 201 Created dönmemiz, hatta eğer veriyi senkron şekilde oluşturmuyorsak 201 Accepted dönmemiz ve sonucunda sonradan kontrol edilebilmesi amacıyla bir takip kodu vermemiz gibi çok daha doğru uygulamalar kullanılmaktadır.
REST API servislerde dilediğimiz kimlik doğrulama metodunu kullanabiliriz fakat genellikle Oauth server üzerine datatracker.ietf.org/doc/html/rfc7519 ile standartlaşan JWT Token kullanılıyor.
Şu ana kadar anlattıklarımız dışında bazı isimlendirme önerileri ise şöyle;
- URI içerisinde yalnızca – kullanılması
- Body içerisindeki alanların isimlendirmesinde CamelCase uygulanması
- Yaygın kullanımı yoksa URI ya da Body içerisindeki kullanımlarda kısaltma kullanılmaması
REST API hakkında daha fazlası için bolca araştırma yapabilirsiniz. Bu konuda size en fayda sağlayacak araştırma yöntemlerinden bir tanesi yaygın kullanıma sahip ürünlerin REST API servislerini incelemek olacaktır.
Kullandığınız ya da yazdığınız servislerin DOWN olmadığı, hiç 429 Too Many Requests almadığınız ya da vermek zorunda kalmadığınız günler dilerim.
