REST API nedir?

REST API, kaynaklar ve bunların temsilleri üzerinden iletişim kuran REST mimari ilkelerine göre tasarlanmış uygulama arayüzüdür. Web üzerinde yaygın uygulaması HTTP kullanır ve kullanıcı, ürün veya sipariş gibi kaynakları URL'lerle tanımlar. İstemci; kullanıcı, ürün veya sipariş gibi bir kaynağa istek gönderir, sunucu da genellikle JSON biçiminde veri ve HTTP durum koduyla yanıt verir. REST bir programlama dili veya veri biçimi değildir; istemci-sunucu ayrımı, durumsuz iletişim, önbellek kuralları ve ortak arayüz gibi kısıtları olan bir mimari stildir. JSON zorunlu değildir.

REST API nasıl çalışır?​

İstemci ile sunucu arasındaki iletişim istek-cevap modeline dayanır. İstekte hedef adres, HTTP yöntemi, başlıklar ve gerekiyorsa gövde bulunur. Sunucu isteği doğrular, yetkilendirmeyi kontrol eder, işlemi gerçekleştirir ve sonucu bir durum koduyla döndürür.

Somut REST API örneği​

Bir görev uygulaması geliştirdiğinizi varsayalım. Görevleri listelemek için istemci şu isteği gönderebilir:


Sunucu başarılı bir yanıtta 200 OK durum kodu ve aşağıdakine benzer bir JSON döndürebilir:


Yeni görev eklemek için istek gövdesi gönderilir. Aşağıdaki gösterim, ilgili başlıklar ve JSON gövdesiyle sınırlı şematik bir örnektir:


İşlem başarılıysa sunucu genellikle oluşturulan kaynağı ve 201 Created durum kodunu döndürür. Kaynak bulunamazsa 404 Not Found, istek verisi hatalıysa 400 Bad Request, kimlik doğrulama eksik veya geçersizse 401 Unauthorized kullanılabilir. Durum kodu, istemcinin sonucu nasıl ele alacağını belirlemesine yardımcı olur.

Kaynaklar ve HTTP yöntemleri​

Kaynak, yalnız bir veri türü değil; tanımlanabilen bir kullanıcı, koleksiyon, belge veya hizmet kavramı olabilir. İstemci çoğunlukla kaynağın kendisiyle değil, JSON veya başka biçimdeki temsiliyle çalışır. Örneğin kullanıcılar için /users, belirli bir kullanıcı için /users/42 kullanılabilir. Kaynağın ne yapılacağını ise HTTP yöntemi belirtir:
Bu yöntemlerin anlamını karıştırmamak önemlidir. Örnekte yeni kullanıcı eklemek için GET kullanılmaz; koleksiyona POST gönderilir. API sözleşmesi izin veriyorsa bilinen bir hedef URL'de PUT da kaynak oluşturabilir. Yalnızca e-posta adresini değiştirmek için PATCH uygunken, kaynağın tüm alanlarını yeni içerikle değiştirmek için PUT tercih edilir.

REST ilkelerini tasarıma aktarma​

Durumsuz iletişim, her isteğin anlaşılması için gereken bağlamı taşımasıdır; sunucunun kullanıcı veya sipariş verisi saklayamayacağı anlamına gelmez. Yanıtların önbelleğe uygun olup olmadığı belirtilir; her yanıtın önbelleğe alınması gerekmez. Katmanlı yapı ise istemcinin bir geçit veya ara sunucu üzerinden çalışabilmesine izin verir.

Tam REST yaklaşımında ortak arayüz; kaynak kimliği, temsiller, kendini açıklayan mesajlar ve sonraki işlemleri bağlantılarla sunan hipermedya denetimlerini de kapsar. Aşağıdaki örnekler temel HTTP kullanımını gösterir; tek başına bir API'nin bütün REST kısıtlarını karşıladığını kanıtlamaz.

REST API tasarlarken uygulanabilir kararlar​

1. Kaynakları isimlerle ve tutarlı URL'lerle tanımlayın. /getTasks gibi eylem merkezli adresler yerine /tasks kullanın.
2. İşlemin amacını HTTP yöntemiyle ifade edin; URL'ye gereksiz şekilde /create veya /delete eklemeyin.
3. İstek ve yanıt biçimini açıkça belirleyin. JSON kullanıyorsanız Content-Type: application/json başlığını doğru yönetin.
4. Başarılı ve hatalı sonuçlar için anlamlı HTTP durum kodları döndürün. Hata yanıtlarında istemcinin düzeltebileceği alanları açıklayın.
5. Kimlik doğrulama ve yetkilendirmeyi ayırın. Kullanıcının kim olduğu ile belirli kaynağa erişip erişemeyeceği aynı kontrol değildir.
6. Listeleme uç noktalarında filtreleme, sıralama ve sayfalama kurallarını baştan belirleyin; yanıt biçimini sonradan değiştirmek istemci uyumluluğunu bozabilir.

Sık yapılan hatalar​

REST API'yi yalnızca JSON döndüren her servis sanmak yaygın bir hatadır. JSON biçimi tek başına REST anlamına gelmez; kaynakların tutarlı modellenmesi ve HTTP semantiğinin doğru kullanılması da gerekir. Her işlem için 200 OK döndürmek de hatalı tasarıma yol açabilir; istemcinin oluşturma, doğrulama, yetki ve sunucu hatalarını ayırt edebilmesi gerekir.

Bir başka hata, hassas bilgileri URL sorgu parametrelerine koymaktır. URL'ler günlüklerde veya tarayıcı geçmişinde görülebileceğinden parolalar ve erişim belirteçleri burada taşınmamalıdır. Ayrıca istemcinin gönderebileceği alanlar doğrulanmalı, yalnızca arayüzde gizlemek güvenlik önlemi sayılmamalıdır.

Sık sorulan sorular​

REST API ile SOAP arasındaki temel fark nedir?​

REST mimari stildir; SOAP ise XML tabanlı bir mesajlaşma çerçevesi/protokolüdür ve farklı taşıma protokolleriyle kullanılabilir. REST'in HTTP üzerindeki yaygın uygulamasıyla SOAP'ı yalnız “biri JSON, diğeri XML” diye ayırmak eksik kalır. Seçim mevcut entegrasyon sözleşmesine ve gereksinimlere bağlıdır.

REST API kullanmak bağlantıyı otomatik olarak şifreler mi?​

Hayır. REST tasarım yaklaşımı, taşıma şifrelemesinden ayrıdır. Web API'sini HTTPS ile sunmak gerekir; ayrıca kimlik doğrulama, kaynak bazında yetki kontrolü ve giriş doğrulaması uygulanmalıdır. HTTPS de tek başına bu uygulama kontrollerinin yerini tutmaz.