Bir sipariş uygulamasında müşteri listesini çekmek ve yeni sipariş oluşturmak aynı sunucuya istek gönderir; fakat bu iki isteğin etkisi aynı değildir. HTTP metodu, istemcinin sunucudan ne beklediğini anlatır. Metodu seçerken yalnızca rota adının güzel görünmesine değil, isteğin yan etkisine ve tekrarlandığında ne olacağına bakmak gerekir.

GET: Veriyi okumak

GET /api/products/42 ürünün bir temsilini ister. GET güvenli bir metot olarak tanımlanır: istemci sunucuda bir iş değişikliği talep etmez. Sunucunun istek kaydı tutması gibi olağan yan etkiler olabilir; ancak GET ile sipariş oluşturmak veya kullanıcı silmek doğru bir tasarım değildir. Çünkü tarayıcı, önbellek, bağlantı önizleyicisi ya da bir arama robotu bir bağlantıyı yeniden isteyebilir.

Ayrıca GET isteğinin URL'sine parola, erişim anahtarı veya kişisel veri koymayın. URL'ler geçmişte, erişim günlüklerinde ve bazı ara sistemlerde kalabilir. Kişiye özel yanıtların önbelleğe alınıp alınmayacağını ayrıca Cache-Control ile belirlemek gerekir.

POST ve PUT arasındaki ayrım

POST genellikle koleksiyona yeni kaynak eklemek ya da kaynağın kendi kurallarına göre bir işlem başlatmak için kullanılır: POST /api/orders. Sunucu yeni kimliği üretip sonucu ve uygunsa Location başlığını döndürebilir. POST kendiliğinden idempotent değildir; aynı isteği iki kez göndermek iki sipariş oluşturabilir.

PUT ise belirli bir URI'deki kaynağın gönderilen temsille oluşturulmasını veya değiştirilmesini ifade eder: PUT /api/products/42. HTTP anlamında idempotenttir; aynı istek bir kez de birkaç kez de uygulandığında amaçlanan etki aynı olmalıdır. Bu, her yanıtta aynı durum kodunun döneceği veya sunucunun hiçbir günlük kaydı tutmayacağı anlamına gelmez.

KOD
PUT /api/products/42 HTTP/1.1
Content-Type: application/json

{"name":"Masa lambası","price_cents":159900,"active":true}

Bu örnekte PUT'u tam temsil olarak ele alıyorsanız, eksik alanların ne olacağını sözleşmede açıkça yazın. Kısmi güncellemeyi gizlice tam güncelleme gibi sunmak istemcilerin veriyi yanlışlıkla kaybetmesine neden olabilir.

PATCH ve DELETE ne yapar?

PATCH bir kaynağa kısmi değişiklik uygulamak için kullanılır. PATCH /api/products/42 isteğinde yalnızca active alanı gönderilebilir. PATCH her durumda idempotent değildir: “adedi 1 artır” işlemi her tekrarlandığında sonucu değiştirir; “adedi 5 yap” işlemi ise uygun uygulandığında aynı son duruma ulaşabilir. Gövdenin biçimi ve eksik alanların anlamı belgelenmelidir.

DELETE belirlenen kaynağın ilişkisini kaldırmayı ister. İlk istekte 204, sonraki istekte kaynağın artık bulunmadığını belirten 404 dönebilir; son durum aynı olduğu için farklı yanıtlar tek başına idempotentlik ihlali değildir. Gerçekte fiziksel silme mi, arşivleme mi yapıldığını ve yetki sınırlarını API sözleşmesinde açıklayın.

İstek başarısız olduysa neyi tekrar edeceğiz?

İstemcinin bağlantısı yanıt gelmeden kopabilir. Bu durumda sunucunun işlemi yapıp yapmadığı bilinmeyebilir. GET için tekrar denemek genellikle daha kolaydır. Ödeme veya sipariş oluşturan bir POST için ise sağlayıcının desteklediği idempotency key gibi bir mekanizma gerekir; rastgele tekrar denemek çift işlem riski doğurur. Her servisin kuralı farklıdır, otomatik retry yazmadan önce sağlayıcının sözleşmesini inceleyin.

Bir metodu seçerken şu üç soruyla başlayın: Kaynak okunuyor mu, yeni bir işlem mi başlatılıyor, mevcut temsil mi değiştiriliyor? Ardından aynı istek tekrarlandığında istenen son durumun ne olacağını ve hata durumunda istemcinin nasıl davranacağını yazın. Bu küçük karar, API büyüdükçe ortaya çıkacak pek çok belirsizliği azaltır.

Daha ayrıntılı tanımlar için MDN HTTP request methods kaynağına bakabilirsiniz.