JSON Patch: API Verilerinizi Akıllıca Güncellemenin Yolu

Modern bir API oluşturdunuz. GET verileri getirir, POST yeni kaynaklar oluşturur—şimdiye kadar sorunsuz. Ancak verileri güncellemeye gelince işler karmaşıklaşıyor.

Diyelim ki bir kullanıcı sadece e-postasını değiştirmek istiyor. Gerçekten de tüm kullanıcı profilini yeniden göndermesini mi istemeniz gerekiyor? Bu hantal, verimsiz ve hataya açık bir durum—özellikle yavaş bağlantılar veya çakışan güncellemelerle.

Daha iyi bir yol var: JSON Patch.
Tüm nesneyi göndermek yerine, yalnızca değişiklikleri gönderirsiniz. Bunu, bir terziye tüm takımı yeniden yaptırmak yerine, yapılacak değişikliklerin bir listesini vermek gibi düşünebilirsiniz.

JSON, API'ler için evrensel bir dil haline geldiğinden, JSON Patch kısmi güncellemeler için hafif ve zarif bir çözüm sunar.

Elbette, JSON Patch ile API'ler tasarlamak ve test etmek doğru araçları gerektirir. İşte burada Apidog devreye giriyor. JSON Patch isteklerini kolayca oluşturmanıza, test etmenize ve doğrulamanıza olanak tanır—böylece tek bir kod satırı yazmadan önce güncellemelerinizin amaçlandığı gibi çalıştığını bilirsiniz. Hepsinden iyisi, bugün ücretsiz olarak indirip denemeye başlayabilirsiniz.

Şimdi, JSON Patch'in ne olduğunu, nasıl çalıştığını ve neden bir sonraki projenizin bir parçası olması gerektiğini inceleyelim.

Sorun: "Kör" PUT İsteği

JSON Patch'in neden bu kadar kullanışlı olduğunu anlamak için öncelikle çözdüğü sorunu anlamamız gerekiyor. Geleneksel olarak, bir RESTful API'deki bir kaynağı güncellemek PUT HTTP metodu ile yapılır.

Bir PUT isteği idempotent (aynı isteği birden çok kez yapmanın bir kez yapmakla aynı etkiyi yaratması) olması amaçlanmıştır ve genellikle hedef URL'deki *tüm* kaynağı istek gövdesinde sağlanan yeni gösterimle değiştirir.

Bir kullanıcı profili kaynağını hayal edelim:

GET /users/123

{
  "id": 123,
  "username": "johndoe",
  "email": "john.old@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "age": 30,
  "accountStatus": "active",
  "preferences": {
    "theme": "light",
    "notifications": true
  },
  "signUpDate": "2023-01-15"
}

Şimdi, John sadece e-posta adresini değiştirmek isterse, tipik bir PUT isteği şöyle görünürdü:

PUT /users/123

{
  "id": 123,
  "username": "johndoe",
  "email": "john.new@example.com", // The changed field
  "firstName": "John",
  "lastName": "Doe",
  "age": 30,
  "accountStatus": "active",
  "preferences": {
    "theme": "light",
    "notifications": true
  },
  "signUpDate": "2023-01-15"
}

Sorunu görüyor musunuz? Verilerin %99'u değişmemiş olsa bile her alanı geri göndermek zorunda kaldık. Bu yaklaşımın birkaç dezavantajı var:

1. Artan Bant Genişliği: Kablo üzerinden çok fazla gereksiz veri gönderiyoruz. Büyük kaynaklar için bu, özellikle mobil ağlarda önemli bir performans düşüşüne neden olabilir.
2. Daha Yüksek Çakışma Riski: John e-postasını düzenlerken başka bir işlem yaş alanını güncellerse, John'un PUT isteği yanlışlıkla o yeni yaşı gönderdiği eski değerle üzerine yazabilir.
3. İstemci İçin Karmaşıklık: İstemci uygulaması önce tüm kaynağı GET etmeli, belirli alanı değiştirmeli ve ardından tümünü geri PUT etmelidir. Bu çok adımlı bir işlemdir ve istemcinin tüm durumu yönetmesini gerektirir.

İşte burada HTTP PATCH metodu devreye giriyor.

Çözüm: HTTP PATCH ve JSON Patch'i Tanıtmak

HTTP PATCH metodu, bir kaynakta kısmi değişikliklere izin vermek için tanıtıldı. Tüm kaynağı değiştiren PUT'un aksine, PATCH kaynağa bir dizi *değişiklik* uygular.

Ancak bir sorun var: HTTP standardı bu "değişikliklerin" formatının ne olması gerektiğini tanımlamaz. Kendi formatınızı icat edebilirsiniz. Şuna benzer bir şey gönderebilirsiniz:

{ "op": "change_email", "value": "new@example.com" }

Ancak bu özel, standart dışı olurdu ve diğer geliştiricilerin sizin özel dilinizi öğrenmesi gerekirdi.

JSON Patch'in doldurduğu boşluk budur. JSON Patch (RFC 6902'de tanımlanmıştır), bir JSON belgesine uygulanacak değişiklikleri belirtmek için standartlaştırılmış bir formattır. Bir JSON belgesinin tam olarak nasıl değiştirilmesi gerektiğini açıklayan net, belirsiz olmayan bir dil sağlar.

HTTP PATCH metodunu bir JSON Patch belgesi olarak biçimlendirilmiş bir gövdeyle birleştirdiğinizde, kısmi güncellemeler gerçekleştirmek için güçlü, standartlara dayalı bir yola sahip olursunuz.

JSON Patch Nasıl Çalışır: Temeller

Bir JSON Patch belgesi her zaman bir JSON dizisidir. Dizideki her öğe bir işlem nesnesidir. Bu işlemler hedef belgeye sırayla uygulanır ve tüm yama atomiktir, yani tek bir işlem bile başarısız olursa, tüm yama iptal edilir ve belge değişmeden kalır.

Her işlem nesnesinin, gerçekleştirilecek eylemi belirten zorunlu bir op üyesi ("operation"ın kısaltması) vardır. En yaygın işlemler add (ekle), remove (kaldır), replace (değiştir), move (taşı) ve copy (kopyala) işlemleridir.

John'un e-postasını değiştirdiği önceki örneğe bakalım. JSON Patch kullanarak istek önemli ölçüde basitleşir:

PATCH /users/123

[
  { "op": "replace", "path": "/email", "value": "john.new@example.com" }
]

İşte bu kadar! Tek bir işlem gönderiyoruz: " '/email' yolundaki değeri bu yeni değerle değiştir." İstek küçük, net ve amaç odaklı. Başka hiçbir alana dokunmuyoruz.

path Özelliğini Anlamak

path özelliği, JSON belgesinde değiştirmek istediğiniz belirli değere gitmek için eğik çizgi tabanlı bir sözdizimi kullanan bir JSON Pointer'dır (RFC 6901).

• "/email" kök düzeyindeki email alanını işaret eder.
• "/preferences/theme" preferences nesnesinin içindeki theme alanını işaret eder.
• "/firstName" firstName alanını işaret eder.

Bu sözdizimi, iç içe JSON yapılarını gezinmek için güçlüdür.

JSON Patch ve JSON Merge Patch Karşılaştırması

Geliştiriciler genellikle JSON Patch (RFC 6902) ile JSON Merge Patch'i (RFC 7386) karıştırır. Açıklayalım.

JSON Patch:

• Bir dizi işlemi tanımlar.
• Çok hassastır ve karmaşık güncellemelere izin verir.
• Örnek: değiştirme, taşıma, kopyalama.

JSON Merge Patch:

• Orijinal belgeye birleşen kısmi bir JSON belgesi gönderir.
• Daha basittir, ancak daha az esnektir.
• Örnek: { "name": "Bob" } ad alanını değiştirir.

Kısaca:

• Basit, yüzeysel güncellemeler için JSON Merge Patch kullanın.
• Karmaşık veya birden çok işlem için JSON Patch kullanın.

JSON Patch İşlemleri

En yaygın işlemleri örneklerle inceleyelim. Hedef belge olarak aynı kullanıcı profilini kullanacağız.

1. `add` İşlemi

add işlemi, bir nesneye veya diziye yeni bir değer eklemek için kullanılır.

Bir nesneye yeni bir özellik ekle:

{ "op": "add", "path": "/twitterHandle", "value": "@johndoe" }

Bu, kullanıcı nesnesine yeni bir twitterHandle alanı ekler.

Bir diziye bir öğe ekle (belirli bir dizine):

Kullanıcının bir "hobbies" dizisi olduğunu hayal edin: ["reading", "cycling"].

{ "op": "add", "path": "/hobbies/1", "value": "hiking" }

Bu, "yürüyüş"ü 1. dizine ekler ve sonuç olarak ["reading", "hiking", "cycling"] olur. Dizinin sonuna eklemek için /- kullanabilirsiniz: { "op": "add", "path": "/hobbies/-", "value": "hiking" }.

2. `remove` İşlemi

remove işlemi, belirtilen bir konumdaki bir değeri siler.

Bir nesneden bir özelliği kaldır:

{ "op": "remove", "path": "/age" }

Bu, kullanıcı nesnesinden tüm age alanını kaldırır.

Bir diziden bir öğeyi kaldır:

{ "op": "remove", "path": "/hobbies/0" }

Bu, hobbies dizisinden ilk öğeyi (0. dizin) kaldırır.

3. `replace` İşlemi

replace işlemi, aynı yolda remove ve add işlemlerinin birleşimidir. Bir konumdaki mevcut değeri yeni bir değerle değiştirir. E-posta örneğimiz klasik bir replace işlemiydi.

Bir kullanıcının tema tercihini değiştir:

{ "op": "replace", "path": "/preferences/theme", "value": "dark" }

4. `move` İşlemi

move işlemi, bir değeri bir konumdan kaldırır ve başka bir konuma ekler.

Bir değeri bir özellikten diğerine taşı:

{ "op": "move", "from": "/firstName", "path": "/first_name" }

Bu, firstName değerini first_name adlı yeni bir özelliğe taşır ve eski firstName özelliğini kaldırır.

5. `copy` İşlemi

copy işlemi, bir değeri bir konumdan başka bir konuma kopyalar. Orijinal değer değişmeden kalır.

Bir ayarın yedeğini oluştur:

{ "op": "copy", "from": "/preferences/theme", "path": "/backupTheme" }

Bu, mevcut tema değerini yeni bir backupTheme alanına kopyalar.

6. `test` İşlemi

Bu bir güvenlik özelliğidir. test işlemi, bir konumdaki bir değerin belirtilen bir değere eşit olup olmadığını kontrol eder. Test başarısız olursa, tüm yama iptal edilir. Bu, çakışmaları önlemek (optimistic locking) için inanılmaz derecede kullanışlıdır.

E-postayı güncellemeden önce başka kimsenin değiştirmediğinden emin ol:

[
  { "op": "test", "path": "/email", "value": "john.old@example.com" },
  { "op": "replace", "path": "/email", "value": "john.new@example.com" }
]

Eğer mevcut email değilse "john.old@example.com" (belki başka bir işlem zaten değiştirmiştir), test işlemi başarısız olur ve replace asla gerçekleşmez. Bu, güncellemenizin bilinen en son duruma dayalı olmasını sağlar.

Neden JSON Patch Kullanmalı? Faydaları

1. Verimlilik: En bariz faydası. Yalnızca değişiklikleri gönderirsiniz, bu da yük boyutunu önemli ölçüde azaltır ve performansı artırır.
2. Eşzamanlılık Kontrolü: test işlemi, optimistic locking için yerleşik bir mekanizma sağlar, kayıp güncellemeleri ve yarış koşullarını önlemenize yardımcı olur.
3. Atomiklik: Bir yama uygulamasının ya hep ya hiç doğası, verilerinizin tutarlı kalmasını sağlar. On işlemlik bir yamadaki beşinci işlem başarısız olursa, ilk dördü geri alınır.
4. Netlik ve Amaç: İstek gövdesi, yeni bir durumu boşaltmak yerine değişikliğin *amacını* ("e-postayı değiştir", "bir hobi ekle") açıkça tanımlar. Bu, günlükleri daha okunabilir ve hata ayıklamayı daha kolay hale getirir.
5. Standardizasyon: Bu bir IETF standardıdır (RFC 6902). Diğer geliştiriciler bunu tanıyacaktır ve farklı programlama dillerindeki birçok kütüphane ve çerçeve, JSON Patch belgelerini ayrıştırmak ve uygulamak için yerleşik desteğe sahiptir.

JSON Patch ile Sık Karşılaşılan Tuzaklar ve Hatalar

JSON Patch güçlü olsa da, geliştiriciler genellikle şu sorunlarla karşılaşır:

• Yanlış yol kullanma (JSON Pointer sözdizimi hataları).
• `value` veya `from` gibi zorunlu alanları unutma.
• Mevcut olmayan yollara yama uygulama.
• `test` işlemlerini yanlış bir şekilde aşırı kullanma.
• JSON Patch'i JSON Merge Patch ile karıştırma.

API'ler Neden JSON Patch Kullanır

API'ler JSON Patch'i sever çünkü:

• Verimli: Yalnızca değişenleri gönderir.
• Atomik: Tek bir istekte birden çok değişiklik.
• Esnek: Taşıma/kopyalama gibi gelişmiş işlemleri destekler.
• Standartlaştırılmış: Farklı sistemlerde çalışır.

Örneğin, GitHub'ın API'si, depo meta verilerini verimli bir şekilde düzenlemek için JSON Patch'i destekler.

REST API'lerinde JSON Patch

RESTful API'lerde, JSON Patch genellikle HTTP PATCH metodu ile kullanılır.

PATCH ve PUT Karşılaştırması:

• PUT tüm kaynağı değiştirir.
• PATCH kaynağın bir kısmını günceller.

JSON Patch ile `Content-Type` şudur:

application/json-patch+json

Bu, sunucuya gövdenin bir JSON Patch belgesi içerdiğini söyler.

GraphQL ve Diğer Protokollerde JSON Patch

JSON Patch öncelikli olarak REST API'lerinde kullanılsa da, şunlarda da geçerliliği vardır:

• GraphQL mutasyonları: Artımlı güncellemeler uygulama.
• JSON yükleriyle gRPC: Yapılandırılmış yamalar gönderme.
• Olay odaklı mimariler: Tam nesneler yerine yalnızca değişiklikleri yayınlama.

JSON Patch Verimliliği Nasıl Artırır

Kullanıcı profillerini senkronize eden bir mobil uygulama hayal edin. Her küçük güncelleme için 2MB'lık bir JSON dosyasını yeniden yüklemek yerine, uygulama sadece küçük bir yama isteği gönderebilir.

Bu şu anlama gelir:

• Daha hızlı senkronizasyon süreleri.
• Daha düşük mobil veri kullanımı.
• Daha iyi sunucu performansı.

Zorluklar ve Dikkat Edilmesi Gerekenler

JSON Patch güçlüdür, ancak karmaşıklıkları da yok değildir.

1. Sunucuda Karmaşık Uygulama: Bir yamayı sunucuda doğru bir şekilde uygulamak, yeni bir JSON nesnesini kabul etmekten daha karmaşıktır. Her işlemi doğrulamanız, mevcut olmayan yollara işaretçileri uygun şekilde ele almanız ve tüm dizinin atomik olarak uygulanmasını sağlamanız gerekir. Neyse ki, çoğu modern web çerçevesi bunu sizin için halleden kütüphanelere sahiptir (örneğin, Node.js için json-patch, Python için jsonpatch, .NET'te JsonPatchDocument).
2. Hata Potansiyeli: Yanlış biçimlendirilmiş bir yama belgesi veya geçersiz bir işaretçi (örneğin, mevcut olmayan bir alanı replace etmeye çalışmak) bir hatayla sonuçlanacaktır. API'nız bunları zarif bir şekilde ele almalı ve net hata mesajları döndürmelidir (genellikle 422 İşlenemeyen Varlık veya 400 Hatalı İstek).
3. Her Derde Deva Değil: Çok basit kaynaklar için, bir PUT hala daha basit olabilir. JSON Patch, kaynaklarınız büyük olduğunda veya karmaşık, koşullu güncellemeleri desteklemeniz gerektiğinde parlar.

Apidog ile JSON Patch Uç Noktasını Test Etme

JSON Patch'i manuel olarak test etmek sinir bozucu olabilir. İşte burada gelişmiş bir API aracı paha biçilmez hale gelir. Hepsi bir arada bir API geliştirme platformu olan Apidog, burada büyük bir kurtarıcı olabilir:

• Test Etme: PATCH uç noktasını görselleştirilmiş bir panoda kolayca test edebilir ve yanıt doğrulama sonuçlarını alabilirsiniz.
• Dokümantasyon: PATCH uç noktalarınızı Apidog içinde belgeleyebilir, diğer ekip üyelerine beklenen formatı açıkça gösterebilirsiniz, bu da işbirliğini geliştirir ve entegrasyon hatalarını azaltır.

Apidog'da örnek iş akışı:

1. Yeni bir istek oluşturun.
2. Metodu PATCH olarak ayarlayın.
3. `Content-Type: application/json-patch+json` ekleyin.
4. JSON Patch dizinizi girin.
5. Anında gönderin ve sonuçları doğrulayın.

Apidog kullanarak, yamanızın doğru olup olmadığını tahmin etmekten, doğru bir şekilde oluşturulduğunu bilmeye geçersiniz, bu da JSON Patch API'lerini güvenle uygulamanıza ve tüketmenize ve JSON Patch'i profesyonel gibi test etmeye başlamanıza olanak tanır.

JSON Patch En İyi Uygulamaları

JSON Patch'i etkili bir şekilde kullanmak için:

1. JSON Patch belgelerinizi göndermeden önce doğrulayın.
2. Tutarlılık önemli olduğunda test işlemlerini kullanın.
3. Verimlilik için yamaları küçük tutun.
4. JSON Patch kullanırken API'nızı açıkça belgeleyin.
5. Testleri kolaylaştırmak için Apidog gibi araçları kullanın.

Sonuç: Daha Verimli Bir API Standardını Benimsemek

Peki, JSON Patch nedir?

Ekleme, kaldırma ve değiştirme gibi işlemleri kullanarak JSON belgelerindeki değişiklikleri tanımlamanın standartlaştırılmış bir yoludur. Tam nesneler göndermek yerine, yalnızca değişiklikleri gönderebilirsiniz, bu da API'lerinizi daha verimli, güvenilir ve esnek hale getirir.

JSON Patch, API'ler üzerinden veri güncelleme şeklimizi dönüştürüyor. Bizi tam belge değiştirme gibi kaba bir araçtan, cerrahi değişikliklerin hassasiyetine taşıyor. Bu standardı benimseyerek, daha verimli, çakışmalara daha az eğilimli ve amaçları daha net API'ler inşa ediyoruz.

Sunucu tarafında biraz daha önceden düşünmeyi gerektirse de, istemci uygulamaları ve ağ performansı için faydaları önemlidir. Bir dahaki sefere bir güncelleme uç noktası tasarlarken, varsayılan PUT'a direnin ve kendinize sorun: "Bu, PATCH için bir iş olabilir mi?"

Geliştiriciler için, JSON Patch'i anlamak, modern API'lerle çalışmanın, özellikle kısmi güncellemeleri ele alırken, anahtarıdır. Ve Apidog gibi araçlarla, JSON Patch isteklerini kolayca test edebilir, doğrulayabilir ve hata ayıklayabilirsiniz.