REST API Nedir?

Bir protokol değil, mimari bir tarz

REST, Roy Fielding'in 2000 yılında yayımladığı doktora tezinde tanımladığı bir mimari tarzdır. Yeni bir protokol getirmez; web'in zaten var olan parçalarını (URL'ler, HTTP metotları, durum kodları, başlıklar) belirli kurallar çerçevesinde kullanmayı önerir. Bu kurallar, yani REST kısıtları şunlardır:

• İstemci-sunucu ayrımı: Kullanıcı arayüzü ile veri saklama birbirinden bağımsız gelişebilir.
• Durumsuzluk (stateless): Her istek, sunucunun onu anlaması için gereken her şeyi kendisi taşır; sunucu iki istek arasında istemciye ait oturum durumu saklamaz. Kimlik bilgisinin her istekte, örneğin bir JWT ile gönderilmesi bu yüzdendir.
• Önbelleklenebilirlik: Yanıtlar önbelleğe alınıp alınamayacaklarını açıkça belirtir.
• Tek tip arayüz: Kaynaklar URI ile tanımlanır, temsilleri (ör. JSON) üzerinden değiştirilir, mesajlar kendi kendini açıklar ve yanıtlar olası sonraki adımlara bağlantı verebilir (HATEOAS).
• Katmanlı sistem: İstemci, arada bir proxy, yük dengeleyici veya CDN olup olmadığını bilmek zorunda değildir.
• İsteğe bağlı kod (code on demand): Sunucu, istemcide çalışacak kod gönderebilir. Tek opsiyonel kısıt budur.

Pratikte “REST API” diye anılan servislerin çoğu bu kısıtların hepsine uymaz; özellikle HATEOAS nadiren uygulanır. Sektörde bu ifade genellikle “kaynak odaklı, HTTP kurallarına saygılı ve JSON konuşan bir API” anlamında kullanılır.

Kaynaklar ve HTTP metotları

REST tasarımında URL bir eylemi değil, bir kaynağı adresler. /orders/1042 REST mantığına uygundur; /getOrder?id=1042 ise eylemi URL'nin içine taşıdığı için uygun değildir. Ne yapılacağını HTTP metodu söyler:

“Güvenli” metot, sunucudaki veriyi değiştirmeyen metottur. Metotların anlamları HTTP standardında, RFC 9110'da tanımlanır.

Idempotency neden önemli?

Bir isteği bir kez göndermekle art arda birkaç kez göndermek sunucuda aynı sonucu doğuruyorsa o istek idempotent'tir. Bağlantı yanıt gelmeden koptuğunda istemci isteğin işlenip işlenmediğini bilemez. Gönderdiği bir PUT ya da DELETE ise isteği gönül rahatlığıyla tekrarlayabilir; POST ise tekrarlandığında ikinci bir sipariş veya ikinci bir ödeme oluşturabilir. Ödeme gibi kritik POST uç noktalarında bu yüzden “idempotency key” deseni kullanılır: istemci her işlem için benzersiz bir anahtar gönderir, sunucu aynı anahtarla gelen ikinci isteği yeniden işlemez ve ilk sonucu döner.

Örnek bir istek ve yanıt

POST /v1/orders HTTP/1.1
Host: api.example.com
Authorization: Bearer <token>
Content-Type: application/json

{"productId": "SKU-881", "quantity": 2}

HTTP/1.1 201 Created
Location: /v1/orders/1042
Content-Type: application/json

{"id": 1042, "status": "pending", "total": "1499.90"}

Sunucu yeni kaynağın oluşturulduğunu 201 Created ile bildiriyor ve adresini Location başlığında veriyor. İstemci siparişi daha sonra GET /v1/orders/1042 ile okuyabilir.

Durum kodlarını doğru kullanmak

İyi bir REST API sonucu yanıt gövdesine gömmek yerine HTTP durum kodlarıyla anlatır:

• 200 OK, 201 Created, 204 No Content: işlem başarılı.
• 400 Bad Request, 422 Unprocessable Content: istemcinin gönderdiği veri hatalı.
• 401 Unauthorized: kimlik doğrulanamadı; 403 Forbidden: kimlik belli ama bu işleme yetkisi yok.
• 404 Not Found, 409 Conflict: kaynak yok ya da istek kaynağın mevcut durumuyla çakışıyor.
• 429 Too Many Requests: hız sınırı aşıldı.
• 500 ve 503: sorun sunucu tarafında.

Her durumda 200 dönüp hatayı gövdedeki bir "error": true alanıyla bildirmek, istemcilerin, proxy'lerin ve izleme araçlarının hataları fark etmesini zorlaştırır.