Tutorial

HTTP PUT ve PATCH: JSON Merge Patch ile Doğru Güncelleme

Mehmet Fatih Ünal
10 Kasım 2026
7 dk okuma
#HTTP#PUT#PATCH#JSON Merge Patch#API Tasarımı
HTTP PUT ve PATCH: JSON Merge Patch ile Doğru Güncelleme

PUT ve PATCH arasındaki temel fark nedir?

PUT, hedef kaynağın durumunu gönderilen gösterimle oluşturma veya değiştirme niyetini taşır. PATCH ise kaynağa uygulanacak değişiklikleri anlatan bir belge gönderir. RFC 9110 PUT bölümü ve RFC 5789, yöntemlerin bu ayrımını tanımlar.

Bu ayrım yalnızca gövdenin küçük veya büyük olması değildir. İki alanlı bir kaynak için küçük bir PUT, tam durumu ifade edebilir. Büyük bir PATCH ise pek çok değişiklik taşıyabilir. İstemci ve sunucu, eksik alanın ne anlama geldiğinde anlaşmalıdır.

Tam değiştirme isteği nasıl görünür?

Örnekte bir profilin yazılabilir gösterimi name, isteğe bağlı note ve tags alanlarından oluşsun. Başlangıç durumu şöyledir:

{"name":"Ada","note":"Old","tags":["news","tips"]}

İstemci yeni tam durumda note istemiyorsa, bu örnek API sözleşmesinde şu PUT gönderilebilir. HTTP blokları ilgili başlıkları gösteren kısaltılmış örneklerdir:

PUT /profiles/42 HTTP/1.1
Host: api.example
Content-Type: application/json
If-Match: "profile-v1"

{"name":"Ada","tags":["news"]}

Bu örnekte gövde, yazılabilir gösterimin tamamıdır. Gerçek bir API'nin zorunlu alanları, sunucu tarafından yönetilen alanları ve varsayılanları ayrıca belgelenmelidir. PUT, bütün veri modellerinde her eksik alanın otomatik olarak aynı biçimde silineceği anlamına gelen bir şema değildir.

JSON Merge Patch hangi değişiklik kurallarını kullanır?

JSON Merge Patch, PATCH ile kullanılabilen belirli bir belge biçimidir. RFC 7396, nesne üyelerini ekleme veya değiştirmeyi, null ile kaldırmayı ve nesne olmayan değerlerin değiştirilmesini tanımlar.

Aynı başlangıç profili üzerinde note alanını kaldırmak ve tags dizisini değiştirmek için alternatif istek şöyledir:

PATCH /profiles/42 HTTP/1.1
Host: api.example
Content-Type: application/merge-patch+json
If-Match: "profile-v1"

{"note":null,"tags":["news"]}

name gönderilmediği için korunur. note içindeki null, bu biçimde alanı null değerine ayarlamak yerine kaldırır. tags ise eleman bazında birleştirilmez; yeni dizi eskisinin yerini alır. Beklenen son belge şudur:

{"name":"Ada","tags":["news"]}

Bir alanda gerçek null değerini saklamak ile alanı kaldırmak arasında ayrım gerekiyorsa, bu biçimin uygunluğunu ayrıca değerlendirin. JSON Patch başka bir biçimdir ve başka medya türü kullanır; PATCH yöntemi tek başına hangi belge dilinin kabul edildiğini söylemez.

Başarılı yanıt ve sürüm koşulu nasıl ele alınır?

Bu örnekte API başarılı değişiklikten sonra gövdesiz 204 ve güncel gösterimin ETag değerini döndürür:

HTTP/1.1 204 No Content
ETag: "profile-v2"

Başka bir istemci kaynağı değiştirmişse eski If-Match koşulu başarısız olabilir. Örnekteki sunucu, böyle bir isteği uygulamadan şu yanıtı verir:

HTTP/1.1 412 Precondition Failed
Content-Length: 0

If-Match başvurusu, eşzamanlı değişikliklerin kontrolüne yardımcı olan koşulu açıklar. Sürüm kontrolü ile yazmayı tek bir atomik karar olarak uygulamak gerekir. Önce sürümü okuyup daha sonra koşulsuz yazmak, aradaki başka bir düzenlemeyi korumaz. If-Match rehberi bu sorunu ayrıntılandırır.

PATCH her zaman idempotent midir?

PATCH genel olarak idempotent kabul edilemez; davranış değişiklik belgesine ve işleme bağlıdır. Aynı alanlara aynı değerleri uygulayan bu Merge Patch örneği ile bir sayacı artıran özel işlem aynı tekrar davranışına sahip değildir. PUT ise HTTP tarafından idempotent yöntem olarak tanımlanır.

Idempotent olmak, her tekrarda aynı yanıtın geleceğini garanti etmez. İlk isteğin ardından sürüm değiştiyse aynı eski If-Match ile tekrar gönderilen istek 412 alabilir. Burada amaçlanan etki ile yanıt kodunu birbirinden ayırın. Retry rehberi, yeniden denemeyi bu ayrımla tasarlamayı ele alır.

Doğrulama ve atomiklik nerede devreye girer?

PATCH belgesi kısmen uygulanıp daha sonra hata döndürülmemelidir. Sunucu değişiklik kümesini bütünüyle uygulamalı veya uygulamamalıdır. Örneğin note kaldırılırken tags alanına geçersiz tür verilmişse, doğrulama başarısız olduğunda eski belge korunmalıdır.

Merge Patch kurallarını uygulamak, kullanıcıya bütün alanları değiştirme izni vermek anlamına da gelmez. Kabul edilen alanlar, alan türleri ve sonuç belgesinin geçerliliği API sözleşmesinde belirlenmelidir. İç içe nesneler, diziler ve null davranışı için ayrı örnekler yazmak, belirsiz bir kısmi güncelleme sözleşmesinden daha anlaşılırdır.

Sık sorulan sorular

PATCH gövdesinde application/json yeterli mi? Bu örnek API, Merge Patch için application/merge-patch+json bekler. Kabul edilen medya türü sözleşmeye bağlıdır.

Merge Patch dizileri birleştirir mi? Hayır. Örnekteki yeni tags dizisi öncekinin tamamının yerini alır.

204 gelince JSON okumalı mıyım? Bu örnekte yanıt gövdesi yoktur. İstemci gövdesiz başarı durumunu ayrıca ele almalıdır.

Daha Fazla İçerik

Blog sayfasında diğer yazılarımı keşfedin

Tüm Yazılar