HTTP put nedir?

HTTP PUT, istemcinin belirli bir kaynak adresindeki veriyi gönderdiği temsille oluşturmasını veya mevcut temsili değiştirmesini isteyen HTTP metodudur. Örneğin bir kullanıcının profilini /users/42 adresinde güncellemek için PUT kullanabilirsiniz. PUT işlemi genellikle tam kaynak güncellemesi için tercih edilir; yalnızca birkaç alanı değiştirmek istiyorsanız PATCH daha uygun olabilir.

PUT isteğinde kaynak adresi istemci tarafından bilinir. Sunucu isteği kabul ederse mevcut kaynağı gönderilen temsille değiştirir veya destekliyorsa o adreste yeni bir kaynak oluşturur. Başarılı yanıt 200 OK, 204 No Content ya da yeni kaynak oluşturulduğunda 201 Created olabilir. Hangi durum kodunun kullanılacağı API sözleşmesinde belirtilmelidir.

PUT nasıl çalışır?​

Bir PUT isteği genellikle şu parçalardan oluşur:

1. Hedef kaynağın kesin adresi belirlenir. Örneğin /users/42 adresi belirli bir kullanıcıyı temsil eder.
2. İstek gövdesine kaynağın gönderilecek temsili yazılır.
3. Gövdenin biçimi Content-Type: application/json gibi bir başlıkla belirtilir.
4. Sunucu veriyi doğrular, yetkiyi kontrol eder ve kaynağı oluşturur veya değiştirir.
5. İstemci durum kodunu ve gerekiyorsa yanıt gövdesini kontrol eder.

Örneğin mevcut bir kullanıcı kaydını PUT ile göndermek şöyle görünebilir:


Bu örnekte sunucu isteği kabul ederse /users/42 kaynağını gönderilen temsile göre günceller. API tam kaynak bekliyorsa gövdede bulunmayan alanlar silinebilir, varsayılan değere dönebilir veya doğrulama hatasına neden olabilir. Bu davranış tahmin edilmemeli; API sözleşmesinden kontrol edilmelidir.

PUT, PATCH ve POST farkı​

Metot seçimi, istemcinin hedef adresi ve yaptığı değişikliğin niteliğine göre yapılır:


Örneğin kullanıcı kimliği istemci tarafından belirleniyorsa PUT /users/42 mantıklıdır. Yeni kullanıcı kimliğini sunucunun üretmesini istiyorsanız POST /users daha uygun olabilir. Yalnızca e-posta alanını değiştirmek için PUT kullanmak yerine PATCH kullanılması, istemeden diğer alanların etkilenmesini önleyebilir.

Uygulanabilir kullanım ve kontrol adımları​

1. Güncellemek istediğiniz kaynağın kesin adresini belirleyin. Koleksiyon adresiyle tekil kaynak adresini karıştırmayın.
2. API sözleşmesinde PUT gövdesinin hangi yazılabilir temsili ve zorunlu alanları beklediğini kontrol edin.
3. Zorunlu alanları, veri türlerini ve Content-Type başlığını doğru gönderin.
4. İsteği yetkili bir istemciyle gönderin ve yanıtın durum kodunu değerlendirin. 2xx yanıtı başarı anlamına gelir; ancak dönen kaynağın gerçekten beklenen durumda olduğunu da kontrol edin.
5. İstek başarısızsa 4xx yanıtlarında gövde içindeki doğrulama veya yetki bilgisini inceleyin. 5xx yanıtlarında isteği sınırsız biçimde tekrarlamak yerine sunucu durumunu ve tekrar politikasını değerlendirin.
6. Aynı PUT isteğini güvenli biçimde tekrarlayabilmek için istemci ve sunucu kaynak tanımını tutarlı tutun. Bu özellik, PUT'un idempotent olmasından kaynaklanır; ancak ağ hatası sırasında isteğin sunucuya ulaşıp ulaşmadığını tek başına kesinleştirmez.

Sık yapılan hatalar​

PUT ile PATCH'i eş anlamlı sanmak: PUT çoğunlukla kaynağın tamamını temsil eder. Eksik alanların nasıl ele alınacağı bilinmiyorsa mevcut verinin üzerine yazılması veya alan kaybı yaşanması mümkündür.

Koleksiyona PUT gönderip sunucunun yeni kimlik üreteceğini beklemek: PUT belirli bir hedef adresle ilişkilidir. Sunucunun adres üretmesi bekleniyorsa API'nin POST davranışını kullanın.

Başarıyı yalnızca HTTP durum koduyla varsaymak: 200 veya 204 yanıtı isteğin kabul edildiğini gösterir; uygulamanın iş kuralı sonucunu ayrıca doğrulamak gerekebilir.

Yetkilendirmeyi atlamak: PUT mevcut bir kaynağı değiştirebildiği için sunucu, kullanıcının o kaynağı değiştirme yetkisini ayrıca kontrol etmelidir.

Sık sorulan sorular​

PUT isteği yanıt gövdesi döndürmek zorunda mı?​

Hayır. Güncellemede 200 ile temsil veya 204 ile gövdesiz başarı dönebilir. Yeni hedef kaynak başarıyla oluşturulmuşsa 201 kullanılır. İstemci 204 yanıtını JSON gibi ayrıştırmamalıdır; API sözleşmesindeki durum kodu ve gövde ilişkisini izleyin.

Her tekrarın ayrı günlüğe yazılması idempotent özelliğini bozar mı?​

Hayır. İdempotent, aynı isteğin hedef kaynağa amaçlanan etkisini anlatır; her yanıtın aynı baytlar olması veya hiç log yazılmaması demek değildir. Tekrarda yeni bir sipariş daha üretmek farklıdır. PUT ayrıca salt okuma anlamında güvenli bir yöntem değildir; var olan veriyi değiştirebilir.

Başkasının aradaki güncellemesini ezmemek için ne yapılabilir?​

API destekliyorsa alınan güçlü ETag değeriyle If-Match önkoşulu kullanılabilir. Temsil değişmişse sunucu 412 ile eski sürümün üzerine yazmayı reddedebilir. İdempotent olmak eşzamanlı güncellemeleri kendiliğinden çözmez; istemci çatışmayı kullanıcıya veya iş akışına uygun biçimde ele almalıdır.