RESTful API tasarımında PUT ve PATCH, sunucudaki kaynakları güncellemek için kullanılan iki HTTP yöntemidir, ancak REST API'lerde PUT ile PATCH arasındaki fark, güncellemeleri nasıl gerçekleştirdikleri ve her birinin en uygun olduğu senaryolardır. Her iki yöntem de mevcut verileri değiştirmek için tasarlanmıştır ancak REST API'deki PUT ve PATCH farkını anlamak, geliştiricilerin gerçekleştirmeleri gereken güncellemenin niteliğine göre en iyi seçimi yapmalarına yardımcı olabilir. Bu blog yazısında, PATCH ve güncelleme REST tartışmasına, her birinin ne zaman kullanılacağına odaklanarak REST API'deki PUT ve PATCH farkını inceleyeceğiz ve farklı kullanım durumları için doğru yöntemi seçme konusunda rehberlik sağlayacağız.
REST API'lerinde PUT nedir?
REST API'lerinde PUT ve PATCH arasındaki farkı anlamak için öncelikle PUT'un ne olduğunu bilmemiz gerekir. dayalı Bölüm 9.6 RFC 2616REST API'sindeki PUT yöntemi, ekteki varlığın sağlanan İstek URI'si altında saklanmasını ister.
İstek URI'si halihazırda mevcut bir kaynağa atıfta bulunuyorsa, ekteki varlığın, kaynak sunucuda bulunanın değiştirilmiş bir versiyonu olarak değerlendirilmesi GEREKLİdir. İstek URI'si mevcut bir kaynağa işaret etmiyorsa ve bu URI, istekte bulunan kullanıcı aracısı tarafından yeni bir kaynak olarak tanımlanabiliyorsa, kaynak sunucu, kaynağı bu URI ile oluşturabilir.
Başka bir deyişle PUT yöntemi sunucudaki bir kaynağın tamamını güncellemek için kullanılır. Bu, PUT'u daha "eksiksiz" bir güncelleme haline getirir ve genellikle kaynağın tamamen değiştirilmesi gerektiğinde kullanılır.
Dolayısıyla PUT aşağıdaki kullanım durumları için en iyisidir:
- Kaynağın tamamını güncellemek (örneğin, bir kullanıcı profilini tüm yeni bilgilerle güncellemek).
- Bir öğenin veya kaydın tamamını değiştirme.
- Kaynağın kimliği net olduğunda ve verilerinin tamamen yenilenmesi gerektiğinde.
Gibi sistemlerde Elasticsearch, veri tutarlılığını garanti etmek için bağımsız işlemler gereklidir. Örneğin, Elasticsearch'te bir belgenin PUT kullanılarak güncellenmesi, aynı isteğin istenmeyen yan etkiler olmadan tekrarlanabilmesini sağlar.
REST API'lerinde PATCH nedir?
Artık REST API'lerinde PUT'u ele aldığımıza göre, REST API'lerinde PUT ile PATCH'i karşılaştırmadan önce REST API'lerinde PATCH'in ne olduğuna ve nasıl çalıştığına bir göz atalım. Tanımlandığı gibi RFC5789REST API'sindeki PATCH yöntemi, istek varlığında açıklanan bir dizi değişikliğin İstek URI'si tarafından tanımlanan kaynağa uygulanmasını ister.
Bu, yalnızca değiştirilmesi gereken verileri gönderdiğiniz ve sunucunun bu değişiklikleri kaynağın tamamını değiştirmeden mevcut kaynağa uyguladığı PUT vs PATCH REST API ayrımına uygundur. Geliştiriciler genellikle bu artımlı değişiklikleri temsil etmek için yamalar oluşturarak minimum veri aktarımı ve verimli güncellemeler sağlar.
REST API'deki PATCH yönteminin aşağıdaki kullanım durumları için daha uygun olmasının nedeni budur:
- Bir kaynaktaki alanların yalnızca bir alt kümesini güncellemek (örneğin, bir kullanıcının e-posta adresini veya telefon numarasını değiştirmek). Bir PATCH API örneği, diğer alanlara dokunulmadan yalnızca yeni e-postanın gönderilmesini içerebilir.
- Veri yükünü en aza indirerek performansı artırma.
- Bir kaynağı tamamen değiştirmek yerine aşamalı olarak güncellemek istediğinizde.
- İlgisiz verileri etkilemeden, bir kullanıcının e-postasını değiştirmek gibi belirli alan değişikliklerini özetlemek için yamalar oluşturun.
Gibi platformlar için başsız CMS Genellikle karmaşık içerik yapılarını işleyen sistemlerde PATCH'in tek bir alanı değiştirmek gibi daha küçük güncellemeler için kullanılması sunucu yükünü azaltabilir ve performansı artırabilir.
Bu iki yöntemi ele aldığımızda, REST API'lerinde PUT ve PATCH'in ne olduğu hakkında iyi bir fikre sahip olmalısınız. Ancak REST API'lerinde PUT ve PATCH arasındaki farka girmeden önce bu iki yöntemdeki Idempotence'den bahsetmemiz gerekiyor.
REST API'lerinde PUT ve Patch'te Idempotence
REST API'lerinde eş güç, aynı girişlerle birden çok kez tekrarlandığında aynı sonuçla sonuçlanan bir işlemin özelliğini ifade eder. Bu, aynı isteğin birden çok kez yapılmasının, kaç kez yürütüldüğüne bakılmaksızın sunucu üzerinde aynı etkiye sahip olması gerektiği anlamına gelir. Bu, bir API'de istikrar ve öngörülebilirliğin sağlanması açısından önemlidir. Peki REST API'deki PUT ve PATCH farkıyla ne alakası var?
PUT Yöntemi ve Idempotence
REST API'deki PUT yöntemi her zaman önemsizdir çünkü belirtilen bir URI'deki kaynağın tamamını istekte sağlanan verilerle değiştirmek üzere tasarlanmıştır. Başka bir deyişle, aynı kaynak verileriyle birden çok kez PUT isteği gerçekleştirirseniz sonuç her zaman aynı olacaktır.
PUT neden Idempotent'tir? Bir PUT isteğinde bulunduğunuzda, aslında sunucuya "Bu, bu kaynak için istediğim tam ve kesin durum" diyorsunuz. PUT isteğini ister bir kez ister birçok kez yayınlayın, sonuçta ortaya çıkan kaynak her zaman aynı olacaktır.
Örneğin, bir kullanıcının e-posta adresini güncellediğiniz senaryoyu düşünün. Aynı PUT isteğini birden çok kez yaparsanız kaynak her seferinde aynı verilerle değiştirildiği için sonuç değişmeyecektir.
Örnek:
| PUT /users/1{“kullanıcı adı”: “john_doe”,”email”: “[email protected]”} |
Bu isteği birden çok kez gönderirseniz sonuç her zaman aynı olacaktır:
| {“kullanıcı adı”: “john_doe”,”email”: “[email protected]”} |
Kullanıcının verileri zaten bu olsa bile isteğin tekrar gönderilmesi hiçbir şeyi değiştirmez. Verileri aynı verilerle değiştirir, böylece isteğin etkisi kaç kez tekrarlanırsa tekrarlansın aynı kalır. PUT'u idempotent yapan şey budur.
PATCH Yöntemi ve Idempotence
Öte yandan, REST API'deki PATCH yöntemi de genellikle önemsizdir ancak daha fazla esnekliğe sahiptir. Yama oluşturduğunuzda, tekrarlanan isteklerden kaynaklanan istenmeyen yan etkileri önlemek için işlemlerin bağımsız olduğundan emin olun (ör. bir değer ayarlamak). PATCH'in bağımsız olup olmadığı, işleme ve değiştirilen verilere bağlıdır.
PATCH neden Idempotent'tir? PATCH istekleri için aynılık, aynı yamanın birden çok kez uygulanmasının aynı sonuca yol açacağı anlamına gelir. Bu, yamanın kendisi tekrar tekrar uygulandığında ek yan etkilere veya değişikliklere neden olmadığı sürece geçerlidir. Aynı yamayı aynı verilerle uygulamaya devam ederseniz, ilk uygulamadan sonra sonuç değişmemelidir.
Örneğin, yalnızca bir kullanıcının e-postasını güncelliyorsanız, aynı PATCH isteğini tekrar tekrar göndermek, istek birkaç kez yapılsa bile ilk seferden sonraki sonucu değiştirmeyecektir. Kullanıcının e-posta adresi aynı kalacak ve kaynağın durumu değişmeyecektir.
PATCH API Örneği:
| PATCH /users/1{“e-posta”: “[email protected]”} |
E-posta zaten [email protected] ise, bu PATCH'in tekrar uygulanması hiçbir değişikliğe yol açmayacak ve onu önemsiz hale getirecektir.
Bununla birlikte, PATCH bazı durumlarda eş değersiz de olabilir. Örneğin, bir PATCH işlemi bir sayacı değiştirirse veya bir listeye öğeler eklerse (bir sayıyı artırmak veya bir diziye eklemek gibi), aynı PATCH'in tekrarlanan uygulamaları farklı sonuçlara yol açabilir. Bu, idempotence özelliğini ihlal eder.
İdempotent olmayan API REST PATCH Örneği:
| PATCH /counter/1{“artırma”: 1} |
Bu YAMA'yı tekrar tekrar uygularsanız sayaç artmaya devam edecek ve her seferinde farklı değerler ortaya çıkacaktır. Sonuç her başvuruda değiştiği için bu önemsiz değildir.
Artık temelleri bildiğinize göre, REST API'lerinde PUT ile PATCH arasındaki farkı daha iyi anlamak için bazı örnek senaryolara bakabiliriz.
Örnek Senaryolar: REST API'lerinde PUT ve PATCH karşılaştırması
Teoriyi bir kenara bırakalım, hem idempotent hem de idempotent olmayan işlemler de dahil olmak üzere PUT ve PATCH arasındaki farka örneklerle bakalım.
Senaryo 1: PUT İsteği – Kaynağın Tamamını Değiştirme
Bir e-ticaret sistemindeki ürünleri yönetmek için bir API uç noktası hayal edin. Bir ürünün adı, fiyatı ve açıklaması dahil tüm ayrıntılarını güncellemeniz gerekir. Bu, PUT'un tam ürün kaynağını değiştirmek için kullanıldığı PUT ve PATCH HTTP yönteminin tipik bir örneğidir.
İlk Ürün:
| GET /products/1001{“id”: 1001,”name”: “Dizüstü bilgisayar”,”price”: 999,99,”description”: “Güçlü bir dizüstü bilgisayar.”} |
Ürünün fiyatını ve açıklamasını güncellemek istiyorsunuz. Kaynağın tamamıyla birlikte bir PUT isteği gönderirsiniz:
PUT İsteği:
| PUT /products/1001{“id”: 1001,”name”: “Dizüstü bilgisayar”,”price”: 899,99,”description”: “İndirimli, güçlü bir dizüstü bilgisayar.”} |
Bu PUT isteğini bir veya birden fazla kez yaparsanız sonuç her zaman aynı olacaktır. Ürün detayları yeni fiyat ve açıklamayı yansıtacak şekilde güncellenecek ve her seferinde aynı sonuç ortaya çıkacaktır. Bu, PUT'un bağımsız doğasını sağlar.
Sonuç (PUT İsteğinden Sonra):
| {“id”: 1001,”name”: “Dizüstü bilgisayar”,”price”: 899,99,”description”: “İndirimli, güçlü bir dizüstü bilgisayar.”} |
Senaryo 2: PATCH İsteği – Kaynağın Bir Kısmının Güncellenmesi
Şimdi ürüne ait açıklama gibi detayların sadece bir kısmının güncellenmesi için bir PATCH talebini ele alalım. PATCH API örneği: Ürün açıklamasını değiştirmek ancak fiyatını değiştirmek istemiyorsanız, PATCH daha iyi bir seçimdir. Bunu uygulamak için, bu API REST PATCH örneğindeki açıklama gibi, yalnızca değişiklik gerektiren alanları içeren yamalar oluşturacaksınız.
İlk Ürün:
| GET /products/1001{“id”: 1001,”name”: “Dizüstü bilgisayar”,”price”: 999,99,”description”: “Güçlü bir dizüstü bilgisayar.”} |
YAMA İsteği:
| PATCH /products/1001{“açıklama”: “Hafif, güçlü bir dizüstü bilgisayar.”} |
Bu PATCH isteğini gönderdiğinizde sadece açıklama alanı güncellenecektir. Aynı PATCH isteğini birden çok kez gönderirseniz, ilk güncellemeden sonra açıklama değişmeden kalacak ve bu da isteğin bağımsız olmasını sağlayacaktır.
Sonuç (PATCH İsteğinden Sonra):
| {“id”: 1001,”name”: “Dizüstü bilgisayar”,”price”: 999,99,”description”: “Hafif, güçlü bir dizüstü bilgisayar.”} |
Aynı YAMA'yı tekrar uygularsanız ürün açıklaması ilk YAMA'dan sonrakiyle aynı olacaktır. Sonuç tutarlıdır, bu da PATCH'i bu senaryoda önemsiz kılmaktadır.
Senaryo 3: PATCH İsteği – İdempotent Olmayan İşlem
İdempotent olmayan bir PATCH işlemine bakalım. Bir kullanıcının cüzdan bakiyesi için bir uç nokta olduğunu ve bakiyeyi artırmak istediğinizi varsayalım. PUT ve PATCH arasındaki örnek fark burada gösterilebilir: PATCH her seferinde bakiyeye bir değer ekleyecektir.
İlk Cüzdan:
| GET /users/1/wallet{“kimlik”: 1,”bakiye”: 100,00} |
YAMA İsteği:
| PATCH /users/1/wallet{“artış”: 50,00} |
Bu PATCH isteği cüzdan bakiyesini 50$ artıracak. Bu PATCH isteğini birden fazla kez gönderirseniz, bakiye her PATCH ile artmaya devam edecek ve her seferinde farklı bir sonuca yol açacaktır. Bu aynı değerde değildir çünkü aynı PATCH'i tekrar tekrar uygulamak farklı bir sonuca neden olur.
Sonuç (İlk PATCH İsteğinden Sonra):
| {“kimlik”: 1,”bakiye”: 150,00} |
Sonuç (İkinci PATCH İsteğinden Sonra):
| {“kimlik”: 1,”bakiye”: 200,00} |
Burada PATCH önemsiz değildir çünkü aynı verilerle tekrarlanan istekler farklı sonuçlar doğurur.
Özet: REST API'lerinde PUT ile PATCH Arasındaki Temel Farklılıklar
REST API'de PUT ve PATCH arasındaki temel fark, güncellemeleri nasıl ele aldıklarıdır. PUT tüm kaynağın yerini alır, böylece eksik alanlar silinir ve bu da veri kaybına neden olabilir. Geliştiricilerin, değişmeyen alanların üzerine yazılmasını önlemek ve veri bütünlüğünü korumak için kısmi güncellemeler için yamalar oluşturmasının nedeni budur.
Bu, PATCH'i kısmi güncellemeler için daha verimli hale getirir. Bir PATCH API örneği şu şekildedir: Yalnızca bir kullanıcının e-postasını güncellemek istiyorsanız, yamalar oluşturmak, kullanıcı verilerinin tamamını gerektiren bir PUT isteğinden farklı olarak yalnızca e-posta alanını gönderir.
PUT ile tam veri yükü gereklidir. Bu, her alanın gönderilmesi gerektiği ve eksik alanların silineceği anlamına gelir. Ancak PATCH yalnızca güncellenmesi gereken alanları göndererek özellikle minimum değişiklikle büyük kaynaklar için onu daha verimli hale getirir. REST API'deki PATCH yöntemi, daha odaklı ve daha küçük isteklere olanak tanıyarak veri aktarımını azaltır.
Hem PUT hem de PATCH bağımsızdır. Bu, aynı isteğin tekrarlanmasının aynı sonuca yol açacağı anlamına gelir. Ancak PUT, kaynağın tamamının yerini aldığından daha öngörülebilirdir. PATCH, yalnızca belirli alanları değiştirmek için kullanıldığında, güncellemelerin sunucu tarafından nasıl işlendiğine bağlı olarak farklı sonuçlara yol açabilir.
Örneğin, bir PATCH bir sayacı artırırsa tekrarlanan istekler farklı sonuçlara yol açabilir. Bununla birlikte PATCH API işlemleri de bağımsız olacak şekilde tasarlanabilir.
Sonuç olarak, REST API'deki PUT ve PATCH farkı, güncellemelerin doğasına indirgenmektedir: PATCH kısmi değişiklikler içindir, PUT ise tam kaynak değişimi içindir. Her ikisi de bağımsızdır ancak PATCH daha karmaşık olabilir.
Son Düşünceler
Hem PUT hem de PATCH, REST API tasarımında temel HTTP yöntemleridir, ancak farklı amaçlara hizmet ederler; REST API'deki PUT ve PATCH farkının özü de budur. Bu makalede daha önce ele aldığımız örneklerle PUT ve PATCH arasındaki farkı anlayarak API'nizin verimliliğini, netliğini ve işlevselliğini önemli ölçüde artırabilirsiniz. Kullanım durumunuza göre doğru yöntemi (PATCH ve güncelleme REST) seçerek API'nizi daha verimli, bakımı kolay ve kullanıcı dostu hale getirebilirsiniz. Her zaman güncellemenin doğasını (tam veya kısmi) yanı sıra performans ve veri bütünlüğü üzerindeki etkisini göz önünde bulundurun ve ihtiyaçlarınıza en uygun yöntemi seçin.
