- Konu sahibi
- #1
HTTP PATCH nedir?
HTTP PATCH, bir kaynağın tamamını yeniden göndermeden yalnızca belirli alanlarında kısmi değişiklik yapmak için kullanılan HTTP yöntemidir. Örneğin bir kullanıcı kaydının yalnızca e-posta adresini veya bir ürünün stok durumunu güncellemek istediğinizde PATCH kullanabilirsiniz. İsteğin başarılı olması için sunucunun PATCH yöntemini ve gönderdiğiniz veri biçimini desteklemesi gerekir.
PATCH nasıl çalışır?
İstek URL'si değiştirilecek kaynağı gösterir. Gövde ise yapılacak değişikliği taşır. Sunucu bu değişikliği mevcut kaynağa uygular; istemcinin kaynağın tüm alanlarını tekrar göndermesi gerekmez.
Örnek, JSON Merge Patch destekleyen kontrollü bir API denemesidir; gerçek bir kullanıcı kaydında çalıştırılacak hazır adres değildir. curl komutundaki satır devamı Bash benzeri kabuk içindir; API’nizin kimlik doğrulaması ayrıca gerekir.
Mevcut kullanıcı kaydı şöyle olsun:
Kod:
{
"id": 42,
"name": "Ayşe",
"email": "[email protected]",
"active": true
}Yalnızca kullanıcının etkinlik durumunu değiştirmek için tüm nesneyi göndermek yerine şu isteği kullanabilirsiniz:
Kod:
curl -i -X PATCH "https://example.com/api/users/42" \
-H "Content-Type: application/merge-patch+json" \
-H "Accept: application/json" \
--data '{"active":false}'Bu örnekte
Content-Type başlığı, gövdedeki verinin JSON Merge Patch biçiminde olduğunu belirtir. API farklı bir format bekliyorsa başlık ve gövde o API'nin sözleşmesine göre değiştirilmelidir.PATCH belgesindeki değişiklik kümesi atomik uygulanmalıdır: tamamı uygulanamıyorsa kısmen değiştirilmiş bir kaynak bırakılmamalıdır. Aynı kaydı başkaları da güncelliyorsa API’nin desteklediği ETag/If-Match gibi koşullu isteklerle eski sürümün üzerine yazmayı önleyin.
Başarılı bir yanıtta sunucu güncellenmiş kaydı döndürebilir. Bazı API'ler gövde döndürmeden yalnızca başarı durumunu bildirebilir. Bu nedenle istemci, yalnızca HTTP durum koduna değil, API'nin tanımladığı yanıt biçimine de göre hareket etmelidir. İstek
415 ile reddedilirse veri biçimi veya Content-Type desteklenmiyor olabilir; 404 kaynak bulunamadığını, 422 ise gönderilen değerlerin doğrulamadan geçmediğini gösterebilir.PATCH ile PUT arasındaki fark
Karar verirken temel ayrım, isteğin kaynağın tamamını mı yoksa bir bölümünü mü temsil ettiğidir. Ancak kesin davranış her API'nin dokümantasyonuyla belirlenir; bazı API'ler PUT ve PATCH için özel kurallar uygulayabilir.
| Yöntem | Genel amaç | Gövde beklentisi | Tipik kullanım |
|---|---|---|---|
| PUT | Kaynağın tamamını değiştirmek veya yerine koymak | Genellikle tam kaynak | Kullanıcı profilinin bütün alanlarını göndermek |
| PATCH | Kaynağın bir bölümünü değiştirmek | Yalnız değişiklik veya işlem listesi | Tek bir alanı güncellemek |
| GET | Kaynağı okumak | Genellikle gövde yoktur | Mevcut kaydı görüntülemek |
PATCH kullanırken eksik alanların ne anlama geldiğini varsaymayın. Bir API'de gönderilmeyen alanlar olduğu gibi kalırken başka bir API farklı bir güncelleme kuralı kullanabilir. JSON Merge Patch’te nesne özelliğinin null olması, o özelliğin kaldırılmasını ifade eder; gönderilmeyen özellikler korunur. Bir alana gerçek null değeri atamak gerekiyorsa bu formatın bu sınırlamasını dikkate alın. JSON Patch ise ayrı bir işlem listesi ve
application/json-patch+json medya türü kullanır.Uygulanabilir PATCH adımları
- Değiştirilecek kaynağın kimliğini ve kesin uç noktasını belirleyin. Örneğin
/api/users/42yalnızca 42 numaralı kullanıcıyı hedeflemelidir. - API'nin desteklediği PATCH gövde biçimini öğrenin. JSON Merge Patch için
application/merge-patch+json, işlem tabanlı JSON Patch için farklı bir medya türü kullanılabilir. - Yalnız değiştirilmesi gereken alanları gönderin ve değerlerin veri tipini koruyun. Boolean alanına metin, sayı alanına biçimsiz metin göndermeyin.
- İsteği çalıştırıp HTTP durum kodunu ve yanıt gövdesini kontrol edin. Başarı kodu alınsa bile dönen kaydın beklenen alanı değiştirdiğini doğrulayın.
- Doğrulama, yetki veya çakışma hatasında isteği körlemesine tekrarlamayın. Yanıtın belirttiği alanları düzeltin; kaynak değişmiş olabileceğinden gerekirse kaydı yeniden okuyup yeni duruma göre PATCH hazırlayın.
Sık yapılan hatalar
Bütün kaydı göndermek: Bu, PATCH'in kısmi güncelleme avantajını azaltır ve istemcideki eski bir alanın sunucudaki yeni değerin üzerine yazılmasına yol açabilir.
PUT ile PATCH'i aynı sanmak: PATCH isteğinde alanların eksik bırakılmasının davranışı PUT ile aynı değildir. Kullanılacak yöntemi API sözleşmesine göre seçin.
Medya türünü belirtmemek: Sunucu JSON kabul etse bile hangi PATCH biçiminin gönderildiğini anlayamayabilir.
Content-Type başlığını gövde formatıyla eşleştirin.İdempotent olduğunu varsaymak: Aynı PATCH isteğini iki kez göndermek her zaman ilk istekle aynı sonucu vermez. Alanı doğrudan
false yapmak genellikle aynı sonuca götürürken, “değeri bir artır” gibi işlem tekrarlandığında farklı sonuç doğurabilir. Tekrarlanabilir işlemlerde API'nin çakışma ve tekrar gönderim kurallarını uygulayın.Sık sorulan sorular
PATCH isteğinde gövde göndermek zorunlu mudur?
Genellikle evet; PATCH'in neyi değiştireceğini belirleyen bir gövde veya işlem bilgisi gerekir. Boş gövdenin kabul edilip edilmediği ve ne anlama geldiği API'ye bağlıdır.
PATCH ile bir alanı silebilir miyim?
Bazı API'lerde alanı
null yapmak, bazılarında ise JSON Patch içindeki remove işlemini kullanmak gerekir. Silme davranışını API'nin veri biçimi ve dokümantasyonuna göre uygulayın.