Bir uygulamanın başka bir uygulamayla iletişim kurmasını sağlayan arayüze API denir. Ancak bu iletişimin nasıl düzenleneceği için farklı yaklaşımlar vardır. REST, bunlardan biridir.
REST API'yi anlamanın en iyi yollarından biri, gerçek bir işlem akışını incelemektir. Bir ürün kataloğunda ürünleri listelemek, yeni bir ürün eklemek veya fiyat değiştirmek üzerinden REST'in nasıl çalıştığına bakalım.
REST API Nedir?
REST, Representational State Transfer ifadesinin kısaltmasıdır. Dağıtık sistemlerin iletişimi için tanımlanmış bir mimari yaklaşımdır. REST API ise bu yaklaşımı temel alan bir uygulama arayüzüdür.
REST'in merkezinde kaynak kavramı bulunur. Bir ürün, kullanıcı, sipariş veya makale bir kaynak olabilir. Web üzerinde kaynaklar adreslerle tanımlanır ve genellikle HTTP metotlarıyla işlenir.
Örneğin bir ürünün adresi şöyle olabilir:
https://api.example.com/products/42Bu adres, kimliği 42 olan ürünü tanımlar. Ürünü okumak, değiştirmek veya silmek için farklı adresler oluşturmak yerine, aynı kaynak adresine farklı HTTP metotlarıyla istek gönderilebilir.
Kaynak ve Temsil Arasındaki Fark
Bir kaynak ile onun API üzerinden gönderilen temsili aynı şey değildir. Kaynak, sistemdeki üründür. Temsil ise o ürünün istemciye aktarılabilen biçimidir.
Örneğin sunucuda ürünün açıklaması, tedarikçi bilgisi, maliyeti ve stok hareketleri bulunabilir. Müşteriye açık API ise yalnızca şu alanları gönderebilir:
{
"id": 42,
"name": "Kablosuz Mouse",
"price": 750,
"currency": "TRY",
"stock": 18
}Bu JSON nesnesi ürünün bir temsilidir. Veritabanı kaydının bütün alanlarını veya tablonun yapısını göstermek zorunda değildir.
REST API'lerde JSON yaygın olarak kullanılır; ancak zorunlu değildir. Aynı kaynak, API'nin desteklediği farklı biçimlerde de temsil edilebilir.
Bir REST İsteği Hangi Bilgileri Taşır?
HTTP üzerinden gönderilen bir REST isteğini anlamak için dört parçayı birlikte incelemek gerekir:
- Adres: Hangi kaynağa erişileceğini belirtir.
- HTTP metodu: Kaynak üzerinde yapılmak istenen işlemi belirtir.
- Başlıklar: Veri biçimi ve kimlik doğrulama gibi ek bilgileri taşır.
- İstek gövdesi: İşlem için gönderilen verileri içerir. Her istekte bulunması gerekmez.
Sunucu yanıtında ise durum kodu, yanıt başlıkları ve gerektiğinde bir yanıt gövdesi bulunur. Şimdi bu yapıyı ürün kataloğundaki işlemler üzerinde görelim.
GET ile Ürün Bilgisini Alma
Bir ürünün bilgilerini okumak için GET isteği gönderilir:
GET /products/42 HTTP/1.1
Host: api.example.com
Accept: application/jsonBuradaki Accept başlığı, istemcinin JSON biçiminde yanıt istediğini belirtir. Sunucu isteği başarıyla işlediğinde şöyle bir yanıt verebilir:
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 42,
"name": "Kablosuz Mouse",
"price": 750,
"currency": "TRY",
"stock": 18
}200 OK, isteğin başarılı olduğunu gösterir. Content-Type ise yanıt gövdesinin biçimini belirtir.
Ürün bulunamazsa sunucu 404 Not Found yanıtı verebilir. GET, veri okumak için tasarlanmıştır; ürün silmek veya fiyat değiştirmek gibi işlemler için kullanılmamalıdır.
POST ile Yeni Ürün Oluşturma
Yeni bir ürün oluşturmak için ürün koleksiyonuna POST isteği gönderilebilir:
POST /products HTTP/1.1
Host: api.example.com
Content-Type: application/json
Accept: application/json
{
"name": "Mekanik Klavye",
"price": 2400,
"currency": "TRY",
"stock": 10
}Bu örnekte ürün bilgileri istek gövdesinde yer alır. Sunucu gerekli kontrolleri yapar ve ürünü oluşturursa şu yanıtı verebilir:
HTTP/1.1 201 Created
Location: /products/43
Content-Type: application/json
{
"id": 43,
"name": "Mekanik Klavye",
"price": 2400,
"currency": "TRY",
"stock": 10
}201 Created, yeni bir kaynak oluşturulduğunu belirtir. Location başlığı ise oluşturulan ürünün adresini gösterir.
POST yalnızca kayıt oluşturmak için kullanılmaz. Bununla birlikte koleksiyona yeni kaynak eklemek, REST tabanlı API'lerde yaygın bir kullanım biçimidir.
PUT ve PATCH ile Ürün Güncelleme
PUT ve PATCH güncelleme amacıyla kullanılabilir; ancak aynı anlamı taşımazlar.
PUT: Kaynağın Temsilini Değiştirme
PUT, hedef kaynağın temsilini gönderilen içerikle değiştirmek için kullanılır. API'nin tanımladığı tam, yazılabilir temsilin gönderilmesi beklenir:
PUT /products/42 HTTP/1.1
Host: api.example.com
Content-Type: application/json
{
"name": "Kablosuz Mouse",
"price": 800,
"currency": "TRY",
"stock": 18
}Buradaki “tam temsil”, veritabanındaki bütün sütunları göndermek anlamına gelmez. Hangi alanların gerekli olduğu, API'nin sözleşmesine bağlıdır. Sunucunun ürettiği kimlik veya oluşturulma tarihi gibi alanlar bu kapsamın dışında olabilir.
PATCH: Kısmi Değişiklik Uygulama
Yalnızca ürünün fiyatını değiştirmek istiyorsak PATCH kullanabiliriz:
PATCH /products/42 HTTP/1.1
Host: api.example.com
Content-Type: application/json
{
"price": 800
}Bu örnekte API'nin, gönderilen alanları güncelleyen bir JSON yapısını desteklediği varsayılmıştır. PATCH için farklı belge biçimleri de kullanılabilir. Kabul edilen biçim ve değişikliğin nasıl uygulanacağı dokümantasyonda belirtilmelidir.
Özetle PUT kaynağın temsilini değiştirmeyi, PATCH ise kaynağa kısmi değişiklik uygulamayı ifade eder.
DELETE ile Ürün Silme
Ürünü kaldırmak için kaynak adresine DELETE isteği gönderilir:
DELETE /products/42 HTTP/1.1
Host: api.example.comİşlem tamamlandıysa ve sunucu bir yanıt gövdesi göndermeyecekse şu yanıt kullanılabilir:
HTTP/1.1 204 No ContentAPI, ürünü veritabanından tamamen silebilir veya uygulamanın kurallarına göre pasif hale getirebilir. İstemci açısından önemli olan, kaynağın kaldırılmasına ilişkin davranışın açıkça tanımlanmasıdır.
Aynı İstek Tekrar Gönderilirse Ne Olur?
Ağ bağlantısı kesildiğinde istemci, isteğin sunucuya ulaşıp ulaşmadığını bilemeyebilir. Bu durumda isteği yeniden göndermenin sonucu önem kazanır.
İdempotent bir işlemde aynı isteğin birden fazla kez uygulanmasının sunucudaki amaçlanan etkisi, bir kez uygulanmasıyla aynıdır.
- GET: Kaynağı okur; amaçlanan işlem veri değiştirmek değildir.
- PUT: Aynı temsil tekrar gönderildiğinde hedeflenen kaynak durumu aynı kalır.
- DELETE: Tekrarlanan silme istekleri kaynağı tekrar tekrar silmez; hedeflenen sonuç kaynağın kaldırılmış olmasıdır.
- POST: Tekrarlanan istekler birden fazla kayıt oluşturabilir.
- PATCH: Tekrarlanmasının etkisi, tanımlanan değişikliğe bağlıdır; her PATCH işlemi idempotent değildir.
İdempotent olması, her istekte aynı durum kodunun döneceği anlamına gelmez. İlk DELETE isteği başarılı olabilirken sonraki istek kaynağın artık bulunamadığını belirtebilir.
REST'te Durumsuz İletişim Ne Demektir?
REST'in temel kısıtlarından biri durumsuz iletişim, yani stateless yapıdır. Her istek, sunucunun onu anlayıp işleyebilmesi için gerekli bilgileri taşımalıdır.
Örneğin korumalı bir ürün yönetimi API'sinde istemci, erişim bilgisini her istekte gönderebilir:
PATCH /products/42 HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json
{
"price": 800
}Sunucu bu isteği işlemek için istemcinin daha önce hangi ekranı açtığını veya önceki istekte hangi ürünü seçtiğini hatırlamak zorunda değildir. Ürün adresi, erişim bilgisi ve değişiklik isteğin içinde bulunur.
Bu ilke, sunucunun veritabanı kullanamayacağı anlamına gelmez. Kalıcı kaynak verileri saklanabilir. Ayrıca token kullanmak tek başına durumsuzluk sağlamaz; önemli olan isteğin önceki bir konuşma ya da oturum bağlamına bağımlı olmamasıdır.
REST API'de Önbellek Nasıl Kullanılır?
Ürün bilgileri her saniye değişmiyorsa aynı veriyi her istekte yeniden üretmek gerekmeyebilir. Uygun yanıtlar, belirtilen kurallar çerçevesinde önbelleğe alınabilir.
Örneğin herkese açık bir ürün yanıtında şu başlık kullanılabilir:
Cache-Control: public, max-age=60Bu başlık, yanıtın uygun önbellekler tarafından 60 saniye boyunca taze kabul edilmesine izin verir. Süre, verinin ne kadar güncel olması gerektiğine göre seçilmelidir.
Kişiye özel veya hassas yanıtlar aynı şekilde ortak önbelleğe açılmamalıdır. Önbellek kuralları, verinin niteliğine ve erişim modeline göre belirlenir.
Her HTTP API Bir REST API midir?
Bir API'nin HTTP kullanması, JSON göndermesi ve GET veya POST isteklerini kabul etmesi, bütün REST ilkelerine uyduğu anlamına gelmez.
REST; istemci ve sunucunun ayrılması, durumsuz iletişim, önbellek kuralları, tekdüze arayüz ve katmanlı sistem gibi kısıtlar tanımlar. İsteğe bağlı bir diğer kısıt, istemciye çalıştırılabilir kod gönderilmesidir.
Tekdüze arayüz kapsamında, yanıtların istemciye ilişkili kaynakları ve mümkün olan sonraki işlemleri keşfetme olanağı sunması da bulunur. Bu yaklaşım HATEOAS olarak adlandırılır.
Örneğin bir ürün yanıtı, ürünün detay adresini veya ilişkili kaynakların bağlantılarını içerebilir. Ancak birkaç bağlantı eklemek tek başına bütün REST kısıtlarını karşılamaz. Günlük kullanımda “REST API” ifadesi, bu ilkeleri kısmen uygulayan kaynak odaklı HTTP API'ler için de kullanılır.
REST Yaklaşımının Avantajları ve Sınırları
Kaynak adresleri ve HTTP metotları etrafında kurulan tutarlı yapı, API'nin anlaşılmasını kolaylaştırır. Aynı API, farklı programlama dilleriyle geliştirilmiş web ve mobil uygulamalar tarafından kullanılabilir.
Durumsuz istekler, uygun bir altyapıda işlemlerin farklı sunuculara dağıtılmasını kolaylaştırabilir. Önbellek kullanımı da tekrar eden okuma işlemlerinin maliyetini azaltabilir.
Bununla birlikte bir ekranı doldurmak için çok sayıda kaynak sorgulamak gerekebilir. Canlı sohbet veya çevrim içi oyun gibi sürekli iletişim isteyen özelliklerde WebSocket gibi başka yöntemler kullanılabilir. REST, uygulamanın bütün iletişim ihtiyaçlarını tek başına çözmek zorunda değildir.
Sonuç
REST API'nin temelinde, kaynakların adreslerle tanımlanması ve bu kaynakların temsilleri üzerinden iletişim kurulması bulunur. Bir ürünün adresi aynı kalırken GET ile okunabilir, PUT veya PATCH ile değiştirilebilir ve DELETE ile kaldırılabilir.
REST'i anlamak için yalnızca metot isimlerini öğrenmek yeterli değildir. İsteklerin taşıdığı bilgiler, tekrarlandıklarında oluşturdukları etki, önbellek kuralları ve istemciyle sunucu arasındaki sorumluluklar birlikte değerlendirilmelidir.