في تصميم REST API، يُعدّ PUT وPATCH طريقتين من طرق HTTP المستخدمة لتحديث الموارد على الخادم، غير أن الفرق بين PUT وPATCH في REST API يكمن في آلية تنفيذ التحديثات والسياقات التي يُستخدم فيها كل منهما. كلتا الطريقتين مصمّمتان لتعديل البيانات الموجودة، لكن فهم الفرق بينهما يساعد المطورين على اختيار الطريقة الأنسب بحسب طبيعة التحديث المطلوب. في هذا المقال، نستعرض الفرق بين PUT وPATCH في REST API، ونتناول النقاش حول PATCH مقابل تحديث REST، ومتى يُستخدم كل منهما، مع إرشادات لاختيار الطريقة المثلى وفقاً لحالة الاستخدام.
ما هو PUT في REST API؟
لفهم الفرق بين PUT و PATCH في REST APIs، علينا أولاً أن نعرف ما هي طريقة PUT. استناداً إلى القسم 9.6 من RFC 2616، تطلب طريقة PUT في REST API تخزين الكيان المُرفق تحت Request-URI المحدد.
إذا كان Request-URI يشير إلى مورد موجود مسبقاً، فينبغي اعتبار الكيان المُرفق نسخةً معدَّلة من المورد المقيم على الخادم الأصلي. أما إذا لم يكن Request-URI يشير إلى مورد موجود، وكان بإمكان وكيل المستخدم الطالب تعريف ذلك URI كمورد جديد، فبإمكان الخادم الأصلي إنشاء المورد بهذا URI.
بمعنى آخر، تُستخدم طريقة PUT لتحديث مورد كامل على الخادم. لذلك تُعدّ PUT تحديثاً "شاملاً"، وتُستخدم عادةً حين يكون الاستبدال الكلي للمورد ضرورياً.
تناسب طريقة PUT حالات الاستخدام التالية:
- تحديث مورد كامل (مثل تحديث ملف تعريف المستخدم ببيانات جديدة بالكامل).
- استبدال عنصر أو سجل بأكمله.
- حين تكون هوية المورد واضحة وتحتاج بياناته إلى تحديث شامل.
في أنظمة مثل Elasticsearch، تُعدّ العمليات الآمنة من التكرار ضرورية لضمان اتساق البيانات. فمثلاً، تحديث مستند في Elasticsearch باستخدام PUT يضمن إمكانية تكرار الطلب ذاته دون آثار جانبية غير مقصودة.
ما هو PATCH في REST API؟
بعد أن تناولنا طريقة PUT في REST APIs، لننظر في ما هي طريقة PATCH في REST APIs وكيف تعمل، قبل أن نقارن بين PUT و PATCH في REST APIs. كما هو محدد في RFC 5789، تطلب طريقة PATCH في REST API تطبيق مجموعة التعديلات الموصوفة في كيان الطلب على المورد المحدد بواسطة Request-URI.
هذا ما يميز PATCH عن PUT في REST API، إذ ترسل فقط البيانات التي تحتاج إلى تعديل، ويطبّق الخادم تلك التغييرات على المورد الموجود دون المساس ببقية بياناته. كثيراً ما يُنشئ المطورون تصحيحات (patches) لتمثيل هذه التعديلات التدريجية، مما يقلل حجم البيانات المنقولة ويرفع كفاءة التحديثات.
لذلك تناسب طريقة PATCH في REST API حالات الاستخدام التالية:
- تحديث مجموعة محددة من الحقول في مورد ما (مثل تغيير البريد الإلكتروني أو رقم الهاتف للمستخدم). مثال على طلب PATCH في API: إرسال البريد الإلكتروني الجديد فقط دون التأثير على بقية الحقول.
- تحسين الأداء بتقليل حجم البيانات المُرسلة في الطلب.
- عندما تريد تحديث مورد بشكل جزئي بدلاً من استبداله بالكامل.
- أنشئ تصحيحات لتغليف تغييرات حقول محددة، كتعديل البريد الإلكتروني لمستخدم، دون التأثير على البيانات غير ذات الصلة.
للمنصات مثل نظام CMS بدون واجهة أمامية (headless CMS) التي تتعامل في الغالب مع هياكل محتوى معقدة، يمكن أن يؤدي استخدام PATCH للتحديثات الصغيرة - كتعديل حقل واحد - إلى تخفيف الحمل على الخادم وتحسين الأداء.
بعد تناول هاتين الطريقتين، ينبغي أن تكون لديك فكرة واضحة عن PUT وPATCH في REST APIs. غير أنه قبل الخوض في الفرق بين PUT وPATCH في REST APIs، علينا الحديث عن الخاصية الأمثلية في هاتين الطريقتين.
الفرق في الأثرية بين PUT وPATCH في REST API
في REST APIs، تشير الخاصية الأمثلية إلى صفة العملية التي تُنتج النتيجة ذاتها عند تكرارها مرات عدة بنفس المدخلات. بمعنى أن إرسال الطلب نفسه عدة مرات يجب أن يكون له الأثر ذاته على الخادم، بصرف النظر عن عدد مرات تنفيذه. وهذا أمر جوهري لضمان الاستقرار والتوقعية في API. لكن ما علاقته بالفرق بين PUT وPATCH في REST API؟
طريقة PUT والأمان من التكرار (Idempotence)
طريقة PUT في REST API أمثلية دائماً، إذ صُمِّمت لاستبدال المورد بأكمله عند URI محدد بالبيانات الواردة في الطلب. بعبارة أخرى، إذا أرسلت طلب PUT عدة مرات بنفس بيانات المورد، فستكون النتيجة في كل مرة متطابقة.
لماذا PUT أمثلية؟ حين ترسل طلب PUT، فأنت تخبر الخادم في جوهر الأمر: "هذه هي الحالة الكاملة والدقيقة التي أريدها لهذا المورد." سواء أرسلت الطلب مرة واحدة أو مرات عديدة، سيظل المورد الناتج متطابقاً في كل مرة.
على سبيل المثال، تخيل أنك تحدّث عنوان البريد الإلكتروني لمستخدم. إذا أرسلت نفس طلب PUT مرات متعددة، فلن تتغير النتيجة، لأن المورد يُستبدل في كل مرة بنفس البيانات.
مثال:
| PUT /users/1{"username": "john_doe","email": "[email protected]"} |
إذا أرسلت هذا الطلب عدة مرات، ستكون النتيجة دائماً هي نفسها:
| {"username": "john_doe","email": "[email protected]"} |
حتى لو كانت بيانات المستخدم كذلك بالفعل، فإن إعادة إرسال الطلب لا تغيّر شيئاً. فالبيانات تُستبدل بنفس البيانات، وبالتالي يظل أثر الطلب واحداً بغض النظر عن عدد مرات تكراره. هذا ما يجعل PUT أمثلية.
طريقة PATCH والأمان من التكرار (Idempotence)
طريقة PATCH في REST API، في المقابل، أمثلية هي الأخرى بوجه عام، لكنها أكثر مرونة. عند إنشاء التصحيحات، احرص على أن تكون العمليات أمثلية - كضبط قيمة ثابتة - لتجنب الآثار الجانبية غير المقصودة الناجمة عن تكرار الطلبات. وما إذا كانت PATCH أمثلية أم لا يتوقف على طبيعة العملية والبيانات التي يجري تعديلها.
لماذا PATCH أمثلية؟ بالنسبة لطلبات PATCH، تعني الخاصية الأمثلية أن تطبيق التصحيح ذاته عدة مرات سيُعطي النتيجة نفسها. وهذا صحيح طالما أن التصحيح نفسه لا يُحدث آثاراً جانبية إضافية عند تطبيقه مرات متعددة. إذا طبّقت باستمرار التصحيح ذاته بنفس البيانات، يجب أن تبقى النتيجة دون تغيير بعد التطبيق الأول.
فمثلاً، إذا كنت تحدّث البريد الإلكتروني لمستخدم فحسب، فإن إرسال طلب PATCH ذاته مرات متعددة لن يغيّر النتيجة بعد المرة الأولى، حتى وإن أُرسل الطلب مرات عدة. سيظل البريد الإلكتروني للمستخدم كما هو، ولن تتغير حالة المورد.
مثال على API بـ PATCH:
| PATCH /users/1{"email": "[email protected]"} |
إذا كان البريد الإلكتروني [email protected] مسبقاً، فإن تطبيق هذا الـ PATCH مجدداً لن يُحدث أي تغيير، مما يجعله أمثلياً.
غير أن PATCH قد تكون غير أمثلية في بعض الحالات. فمثلاً، إذا عدّلت عملية PATCH عداداً أو أضافت عناصر إلى قائمة - كزيادة رقم بمقدار معين أو إلحاق عنصر بمصفوفة - فإن تطبيق PATCH ذاته مرات متعددة قد يُفضي إلى نتائج مختلفة. وهذا يخالف خاصية الأمثلية.
مثال على API REST بـ PATCH غير الأمثلية:
| PATCH /counter/1{"increment": 1} |
إذا طبّقت هذا الـ PATCH بشكل متكرر، سيواصل العداد الزيادة، مما ينتج عنه قيم مختلفة في كل مرة. هذا ليس أمثلياً لأن النتيجة تتغير مع كل تطبيق.
بعد أن تعرّفت على الأساسيات، يمكننا النظر في بعض السيناريوهات التطبيقية لفهم الفرق بين PUT وPATCH في REST APIs بشكل أعمق.
أمثلة تطبيقية: PUT مقابل PATCH في REST APIs
بعيداً عن النظرية، لنستعرض الفرق بين PUT وPATCH بأمثلة عملية، تشمل العمليات الأمثلية وغير الأمثلية على حد سواء.
السيناريو الأول: طلب PUT - استبدال مورد كامل
تخيل أن لديك نقطة نهاية API لإدارة المنتجات في منظومة تجارة إلكترونية. تحتاج إلى تحديث جميع تفاصيل منتج معين، بما فيها الاسم والسعر والوصف. هذا مثال نموذجي على HTTP بين PUT و PATCH، حيث يُستخدم PUT لاستبدال بيانات المنتج بالكامل.
المنتج الأولي:
| GET /products/1001{"id": 1001,"name": "Laptop","price": 999.99,"description": "A powerful laptop."} |
تريد تحديث سعر المنتج ووصفه. ترسل طلب PUT مع بيانات المورد كاملة:
طلب PUT:
| PUT /products/1001{"id": 1001,"name": "Laptop","price": 899.99,"description": "A discounted powerful laptop."} |
سواء أرسلت هذا الطلب مرة واحدة أو عدة مرات، ستكون النتيجة دائماً هي نفسها. ستُحدَّث تفاصيل المنتج لتعكس السعر والوصف الجديدين في كل مرة. هذا ما يضمن الطابع الأحادي التأثير لطلبات PUT.
النتيجة (بعد طلب PUT):
| {"id": 1001,"name": "Laptop","price": 899.99,"description": "A discounted powerful laptop."} |
السيناريو الثاني: طلب PATCH - تحديث جزء من مورد
لنأخذ الآن مثالاً على طلب PATCH لتحديث جزء من بيانات المنتج فحسب، كالوصف. مثال على API بـ PATCH: إن أردت تغيير وصف المنتج دون المساس بسعره، فإن PATCH هو الخيار الأنسب. لتنفيذ ذلك، يكفي إرسال الحقول التي تحتاج إلى تعديل فقط، كالوصف في هذا المثال API REST.
المنتج الأولي:
| GET /products/1001{"id": 1001,"name": "Laptop","price": 999.99,"description": "A powerful laptop."} |
طلب PATCH:
| PATCH /products/1001{"description": "A lightweight, powerful laptop."} |
عند إرسال هذا الطلب، لن يتغير سوى حقل الوصف. وإن أرسلته عدة مرات، سيظل الوصف كما هو بعد التحديث الأول، مما يجعل الطلب أحادي التأثير.
النتيجة (بعد طلب PATCH):
| {"id": 1001,"name": "Laptop","price": 999.99,"description": "A lightweight, powerful laptop."} |
إن طبّقت الطلب نفسه مجدداً، سيبقى وصف المنتج كما كان بعد أول PATCH. تتسق النتيجة في كل مرة، وهذا ما يجعل PATCH أحادي التأثير في هذا السيناريو.
السيناريو الثالث: طلب PATCH - عملية متعددة التأثير
لنستعرض مثالاً على عملية PATCH متعددة التأثير. افترض أن لديك نقطة نهاية لرصيد محفظة مستخدم، وتريد زيادة هذا الرصيد. هنا يتضح فرق جوهري بين PUT و PATCH: كل إرسال لطلب PATCH سيضيف قيمة إلى الرصيد من جديد.
المحفظة الأولية:
| GET /users/1/wallet{"id": 1,"balance": 100.00} |
طلب PATCH:
| PATCH /users/1/wallet{"increment": 50.00} |
سيرفع هذا الطلب رصيد المحفظة بمقدار 50 دولاراً. إن كررت الإرسال، سيستمر الرصيد في الارتفاع مع كل طلب، فتختلف النتيجة في كل مرة. هذا هو جوهر العملية متعددة التأثير: تطبيق الطلب أكثر من مرة يُفضي إلى نتائج مختلفة.
النتيجة (بعد طلب PATCH الأول):
| {"id": 1,"balance": 150.00} |
النتيجة (بعد طلب PATCH الثاني):
| {"id": 1,"balance": 200.00} |
هنا، PATCH ليس idempotent لأن تكرار الطلبات بنفس البيانات يُنتج نتائج مختلفة.
ملخص: الفروق الرئيسية بين PUT و PATCH في REST APIs
الفرق الجوهري بين PUT وPATCH في REST API هو طريقة التعامل مع التحديثات. PUT يستبدل المورد بالكامل، وأي حقل غائب سيُحذف، مما قد يؤدي إلى فقدان البيانات. لهذا السبب يلجأ المطورون إلى PATCH للتحديثات الجزئية، تفادياً لاستبدال الحقول التي لم تتغير، والحفاظ على سلامة البيانات.
هذا ما يجعل PATCH أكثر كفاءة في التحديثات الجزئية. مثال على استخدام PATCH API: إذا أردت تحديث بريد المستخدم الإلكتروني فقط، فإن PATCH لن يرسل سوى حقل البريد، على عكس PUT الذي يستلزم إرسال بيانات المستخدم كاملة.
يتطلب PUT إرسال كامل بيانات المورد، أي أن كل حقل يجب أن يُرسل، وأي حقل مفقود سيُحذف. أما PATCH، فلا يرسل إلا الحقول المراد تعديلها، مما يجعله أكثر كفاءة، خاصةً مع الموارد الكبيرة التي تحتاج تغييرات طفيفة. يتيح PATCH في REST API طلبات أصغر وأكثر تركيزاً، مما يقلل من حجم البيانات المنقولة.
كلٌّ من PUT وPATCH هما idempotent، أي أن تكرار نفس الطلب يُعطي النتيجة ذاتها. غير أن PUT أكثر قابلية للتنبؤ، إذ يستبدل المورد بالكامل. أما PATCH، حين يُستخدم لتعديل حقول محددة فقط، فقد تتفاوت النتائج بحسب طريقة معالجة التحديثات على الخادم.
على سبيل المثال، إذا كان PATCH يزيد قيمة عداد، فإن تكرار الطلب قد يُنتج نتائج مختلفة. ومع ذلك، يمكن تصميم عمليات PATCH API لتكون idempotent أيضاً.
خلاصة القول، يتمحور الفرق بين PUT وPATCH في REST API حول طبيعة التحديث: PATCH للتغييرات الجزئية، وPUT لاستبدال المورد بالكامل. كلاهما idempotent، إلا أن PATCH قد يكون أكثر تعقيداً.
الخاتمة
كلٌّ من PUT وPATCH من أساليب HTTP الجوهرية في تصميم REST API، لكنهما يخدمان غرضين مختلفين، وهذا جوهر الفرق بين PUT وPATCH في REST API. يمكنك تحسين كفاءة API ووضوحه ووظائفه بشكل ملموس حين تفهم الفرق بين PUT وPATCH من خلال الأمثلة التي تناولناها في هذا المقال. باختيار الأسلوب الصحيح (PATCH مقابل تحديث REST) بحسب حالة الاستخدام، ستجعل API أكثر كفاءةً وقابليةً للصيانة وسهولةً في الاستخدام. دائماً ضع في اعتبارك طبيعة التحديث، سواء أكان كاملاً أم جزئياً، وأثره على الأداء وسلامة البيانات، ثم اختر الأسلوب الأنسب لاحتياجاتك.
