İyi tasarlanmış REST API yapısında PUT ve PATCH, sunucudaki kaynakları güncellemek için kullanılan iki HTTP metodudur. REST API'lerde PUT vs PATCH arasındaki fark, güncellemelerin nasıl yapıldığında ve her birinin en uygun olduğu senaryolarda yatar. Her iki metot da mevcut verileri değiştirmek için tasarlanmıştır; ancak REST API'de PUT ile PATCH farkını anlamak, geliştiricilerin yapılacak güncellemenin niteliğine göre en doğru seçimi yapmasına yardımcı olur. Bu blog yazısında REST API'deki PUT ve PATCH farkını ele alacağız; PATCH vs güncelleme REST tartışmasına odaklanacak, her birinin ne zaman kullanılacağını açıklayacak ve farklı kullanım senaryoları için doğru metodu seçme konusunda rehberlik edeceğiz.
REST API'lerde PUT nedir?
REST API'lerde PUT vs PATCH farkını anlamak için önce PUT'un ne olduğunu bilmemiz gerekir. Bölüm 9.6 RFC 2616, REST API'deki PUT metodu, gönderilen varlığın belirtilen Request-URI altında saklanmasını talep eder.
Request-URI mevcut bir kaynağa işaret ediyorsa, iletilen varlık kaynak sunucusundaki kaynağın güncellenmiş bir sürümü olarak değerlendirilmelidir. Request-URI 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 söz konusu URI ile kaynağı oluşturabilir.
Kısaca söylemek gerekirse, PUT metodu sunucudaki bir kaynağın tamamını güncellemek için kullanılır. Bu, PUT'u tam anlamıyla kapsamlı bir güncelleme yöntemi haline getirir; özellikle kaynağın tamamen değiştirilmesi gerektiğinde tercih edilir.
PUT aşağıdaki kullanım senaryoları için en uygun seçenektir:
- Bir kaynağın tamamını güncellemek (örneğin, bir kullanıcı profilini tamamen yeni bilgilerle güncellemek).
- Bir kaydı veya öğeyi tamamen değiştirmek.
- Kaynağın kimliği belirli olduğunda ve verilerinin tamamının yenilenmesi gerektiğinde.
Şu gibi sistemlerde Elasticsearch, veri tutarlılığını garanti altına almak için idempotent işlemler gereklidir. Örneğin, Elasticsearch içindeki bir belgeyi PUT ile güncellemek, aynı isteğin istenmeyen yan etkiler olmaksızın tekrarlanabilmesini sağlar.
REST API'lerde PATCH nedir?
REST API'de PUT konusunu ele aldığımıza göre, PUT vs PATCH karşılaştırmasına geçmeden önce REST API'de PATCH'in ne olduğuna ve nasıl çalıştığına bakalım. Tanımına göre RFC 5789, REST API'deki PATCH metodu; istek gövdesinde tanımlanan değişiklikler kümesinin, Request-URI ile belirlenen kaynağa uygulanmasını talep eder.
Bu, PUT vs PATCH REST API ayrımıyla örtüşür: yalnızca değiştirilmesi gereken verileri gönderirsiniz ve sunucu bu değişiklikleri kaynağın tamamını değiştirmeden mevcut kaynağa uygular. Geliştiriciler bu tür artımlı değişiklikleri tanımlamak için genellikle patch'ler oluşturur; böylece veri aktarımı en aza iner ve güncellemeler daha verimli hale gelir.
Bu nedenle REST API'deki PATCH metodu aşağıdaki kullanım senaryoları için daha uygundur:
- Bir kaynaktaki yalnızca belirli alanları güncellemek (örneğin, bir kullanıcının e-posta adresi veya telefon numarasını değiştirmek). PATCH API örneğinde yalnızca yeni e-posta adresi gönderilebilir; diğer alanlar değişmeden kalır.
- Veri yükünü azaltarak performansı artırmak.
- Kaynağı tamamen değiştirmek yerine artımlı olarak güncellemek istediğinizde.
- İlgisiz verileri etkilemeden bir kullanıcının e-postası gibi belirli alan değişikliklerini kapsüllemek için patch'ler oluşturmak.
Şunun gibi platformlar için başsız CMS karmaşık içerik yapılarıyla çalışan platformlarda, tek bir alanı değiştirmek gibi küçük güncellemeler için PATCH kullanmak sunucu yükünü azaltır ve performansı artırır.
Bu iki metodu ele aldığımıza göre, REST API'de PUT ve PATCH'in ne olduğu hakkında yeterli bir fikriniz olmalı. Ancak REST API'de PUT vs PATCH farkına geçmeden önce, bu iki metodda Idempotence konusunu ele almamız gerekiyor.
REST API'lerde PUT ve PATCH'te Idempotence
REST API'lerde idempotence, aynı girdilerle birden fazla kez tekrarlanan bir işlemin her seferinde aynı sonucu üretmesi özelliğini ifade eder. Yani aynı isteği kaç kez yaparsanız yapın, sunucu üzerindeki etkisi değişmez. Bu durum, bir API'de kararlılık ve öngörülebilirliği sağlamak açısından kritik öneme sahiptir. Peki bunun PUT ve PATCH farkıyla ilişkisi nedir?
PUT Metodu ve Idempotence
REST API'deki PUT metodu her zaman idempotent'tir; çü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 PUT isteğini birden fazla kez göndерseniz bile sonuç her zaman aynı olur.
PUT Neden Idempotent'tir? Bir PUT isteği gönderdiğinizde, sunucuya şunu söylemiş olursunuz: "Bu kaynak için tam olarak istediğim durum budur." PUT isteğini bir kez ya da defalarca göndерseniz de elde edilen kaynak her zaman özdeş olacaktır.
Örneğin, bir kullanıcının e-posta adresini güncellediğiniz senaryoyu ele alalım. Aynı PUT isteğini birden fazla kez gönderseniz de sonuç değişmez; çünkü kaynak her seferinde aynı verilerle değiştirilir.
Örnek:
| PUT /users/1{"username": "john_doe","email": "[email protected]"} |
Bu isteği birden fazla kez göndерseniz de sonuç her zaman aynı olacaktır:
| {"username": "john_doe","email": "[email protected]"} |
Kullanıcının verisi zaten bu değerde olsa bile, isteği tekrar göndermek hiçbir şeyi değiştirmez. Veri aynı veriyle değiştirilir, dolayısıyla isteğin etkisi kaç kez tekrarlanırsa tekrarlansın aynı kalır. PUT'u idempotent yapan da budur.
PATCH Metodu ve Idempotence
REST API'deki PATCH metodu ise genel olarak idempotent olmakla birlikte daha fazla esneklik sunar. Patch oluştururken, tekrarlanan isteklerden kaynaklanabilecek istenmeyen yan etkilerden kaçınmak için işlemlerin idempotent olmasına dikkat edin (örneğin bir değer atamak). PATCH'in idempotent olup olmadığı, yapılan işleme ve değiştirilen veriye göre değişir.
PATCH Neden Idempotent Olabilir? PATCH isteklerinde idempotentlik, aynı patch'in birden fazla kez uygulanmasının her seferinde aynı sonucu vermesi anlamına gelir. Bu durum, patch'in tekrar uygulandığında ek yan etkiler veya değişiklikler doğurmaması koşuluyla geçerlidir. Aynı veriyle aynı patch'i uygulamaya devam ederseniz, ilk uygulamanın ardından sonuç değişmez.
Örneğin yalnızca bir kullanıcının e-postasını güncelliyorsanız, aynı PATCH isteğini defalarca göndermek ilk uygulamadan sonra sonucu değiştirmez. Kullanıcının e-postası aynı kalır ve kaynağın durumu değişmez.
PATCH API Örneği:
| PATCH /users/1{"email": "[email protected]"} |
E-posta adresi zaten [email protected] ise bu PATCH'i tekrar uygulamak herhangi bir değişikliğe yol açmaz; bu da onu idempotent yapar.
Ancak PATCH, bazı durumlarda idempotent olmayabilir. Örneğin bir PATCH işlemi bir sayacı artırıyor ya da listeye öğe ekliyorsa (bir sayıyı artırmak veya diziye eleman eklemek gibi), aynı PATCH'in tekrar uygulanması her seferinde farklı sonuçlar doğurabilir. Bu durum idempotentlik özelliğini ihlal eder.
Idempotent Olmayan API REST PATCH Örneği:
| PATCH /counter/1{"increment": 1} |
Bu PATCH'i tekrar tekrar uygularsanız sayaç artmaya devam eder ve her seferinde farklı bir değer elde edilir. Her uygulamada sonuç değiştiğinden bu işlem idempotent değildir.
Temel bilgileri öğrendiğinize göre, REST API'lerde PUT ile PATCH arasındaki farkı daha iyi anlamak için bazı örnek senaryolara bakabiliriz.
Örnek Senaryolar: REST API'lerde PUT vs PATCH
Teorinin ötesine geçip hem idempotent hem de idempotent olmayan işlemler dahil örneklerle PUT ve PATCH arasındaki farka 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 endpoint'i düşünün. Bir ürünün adı, fiyatı ve açıklaması dahil tüm ayrıntılarını güncellemeniz gerekiyor. Bu, PUT'un tam ürün kaynağını değiştirmek amacıyla kullanıldığı HTTP yöntemi PUT vs PATCH'in tipik bir örneğidir.
İlk Ürün:
| GET /products/1001{"id": 1001,"name": "Laptop","price": 999.99,"description": "A powerful laptop."} |
Ürünün fiyatını ve açıklamasını güncellemek istiyorsunuz. Kaynağın tamamıyla birlikte bir PUT isteği gönderiyorsunuz:
PUT İsteği:
| PUT /products/1001{"id": 1001,"name": "Laptop","price": 899.99,"description": "A discounted powerful laptop."} |
Bu PUT isteğini bir kez veya birden fazla kez yapsanız da sonuç her zaman aynı olur. Ürün ayrıntıları yeni fiyatı ve açıklamayı yansıtacak şekilde güncellenir; her seferinde aynı sonuç elde edilir. Bu durum PUT'un idempotent yapısını güvence altına alır.
Sonuç (PUT İsteğinin Ardından):
| {"id": 1001,"name": "Laptop","price": 899.99,"description": "A discounted powerful laptop."} |
Senaryo 2: PATCH İsteği - Kaynağın Bir Bölümünü Güncelleme
Şimdi ürün ayrıntılarının yalnızca bir bölümünü, örneğin açıklamayı güncellemek için yapılan bir PATCH isteğini ele alalım. PATCH API örneği: Ürün açıklamasını fiyatını değiştirmeden güncellemek istiyorsanız PATCH daha iyi bir seçimdir. Bunu uygulamak için yalnızca değiştirilmesi gereken alanları içeren patch'ler oluşturursunuz; bu API REST PATCH örneğinde olduğu gibi yalnızca açıklama alanını içeren bir patch hazırlarsınız.
İlk Ürün:
| GET /products/1001{"id": 1001,"name": "Laptop","price": 999.99,"description": "A powerful laptop."} |
PATCH İsteği:
| PATCH /products/1001{"description": "A lightweight, powerful laptop."} |
Bu PATCH isteğini gönderdiğinizde yalnızca açıklama alanı güncellenir. Aynı PATCH isteğini birden fazla kez gönderirseniz, ilk güncellemeden sonra açıklama değişmez ve bu durum isteği idempotent yapar.
Sonuç (PATCH İsteğinden Sonra):
| {"id": 1001,"name": "Laptop","price": 999.99,"description": "A lightweight, powerful laptop."} |
Aynı PATCH isteğini tekrar gönderirseniz, ürün açıklaması ilk PATCH'ten sonraki haliyle aynı kalır. Sonuç tutarlıdır; bu da PATCH'i bu senaryoda idempotent yapar.
Senaryo 3: PATCH İsteği - Idempotent Olmayan Operasyon
Idempotent olmayan bir PATCH operasyonuna bakalım. Bir kullanıcının cüzdan bakiyesine ait bir endpoint olduğunu ve bakiyeyi artırmak istediğinizi varsayalım. PUT ile PATCH arasındaki fark burada net biçimde görülür: PATCH, her çağrıldığında bakiyeye bir değer ekler.
İlk Cüzdan:
| GET /users/1/wallet{"id": 1,"balance": 100.00} |
PATCH İsteği:
| PATCH /users/1/wallet{"increment": 50.00} |
Bu PATCH isteği cüzdan bakiyesini 50 dolar artırır. Aynı isteği birden fazla kez gönderirseniz bakiye her seferinde artmaya devam eder ve her seferinde farklı bir sonuç elde edersiniz. Aynı PATCH'i tekrar tekrar uygulamak farklı sonuçlar doğurduğu için bu operasyon idempotent değildir.
Sonuç (Birinci PATCH İsteğinden Sonra):
| {"id": 1,"balance": 150.00} |
Sonuç (İkinci PATCH İsteğinden Sonra):
| {"id": 1,"balance": 200.00} |
Burada PATCH idempotent değildir; çünkü aynı veriyle yapılan tekrarlı istekler farklı sonuçlar üretir.
Özet: REST API'lerde PUT ve PATCH Arasındaki Temel Farklar
REST API'de PUT ile PATCH arasındaki temel fark, güncellemeleri nasıl ele aldıklarıdır. PUT kaynağın tamamını değiştirdiğinden eksik alanlar silinir ve bu durum veri kaybına yol açabilir. Bu nedenle geliştiriciler kısmi güncellemeler için PATCH kullanır; böylece değiştirilmemiş alanların üzerine yazılmaz ve veri bütünlüğü korunur.
Bu durum, PATCH'i kısmi güncellemeler için daha verimli kılar. Bir PATCH API örneği şudur: yalnızca kullanıcının e-posta adresini güncellemek istiyorsanız PATCH yalnızca e-posta alanını gönderir; oysa PUT tüm kullanıcı verisini göndermek zorundadır.
PUT ile tüm veri yükü gönderilmek zorundadır; yani her alan belirtilmeli, eksik alanlar ise silinir. PATCH ise yalnızca güncellenmesi gereken alanları gönderir. Bu da özellikle büyük kaynaklarda küçük değişiklikler yapılırken PATCH'i çok daha verimli kılar. REST API'deki PATCH metodu daha odaklı ve küçük isteklere olanak tanır, böylece veri transferini azaltır.
PUT ve PATCH'in her ikisi de idempotent'tir. Bu, aynı isteği tekrarlamanın her seferinde aynı sonucu vereceği anlamına gelir. Ancak PUT, kaynağın tamamını değiştirdiği için daha öngörülebilirdir. PATCH yalnızca belirtilen alanları güncellediğinde ise sonuçlar, sunucunun güncellemeleri nasıl işlediğine bağlı olarak farklılık gösterebilir.
Örneğin, bir PATCH bir sayacı artırıyorsa tekrarlı istekler farklı sonuçlar doğurabilir. Bununla birlikte, PATCH API operasyonları idempotent olacak şekilde de tasarlanabilir.
Sonuç olarak, REST API'de PUT ile PATCH arasındaki fark, güncellemenin niteliğine dayanır: PATCH kısmi değişiklikler için, PUT ise kaynağın tamamen değiştirilmesi için kullanılır. Her ikisi de idempotent'tir; ancak PATCH daha karmaşık olabilir.
Son Düşünceler
PUT ve PATCH, REST API tasarımının temel HTTP metotlarıdır ve her birinin farklı bir amacı vardır; PUT ile PATCH arasındaki farkın özü de budur. Bu makalede ele aldığımız örnekler aracılığıyla 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 metodu seçerek (PATCH mı yoksa tam güncelleme REST mi) API'nizi daha verimli, bakımı kolay ve kullanıcı dostu hale getirebilirsiniz. Güncellemenin tam mı yoksa kısmi mi olduğunu, performans ve veri bütünlüğüne etkisini göz önünde bulundurun ve ihtiyaçlarınıza en uygun metodu seçin.
