في تصميم RESTful API، يعد PUT وPATCH طريقتين HTTP تستخدمان لتحديث الموارد على الخادم، ولكن الفرق بين PUT وPATCH في REST APIs يكمن في كيفية إجراء التحديثات والسيناريوهات التي يكون كل منها أكثر ملاءمة. تم تصميم كلتا الطريقتين لتعديل البيانات الموجودة، ولكن فهم الفرق بين PUT وPATCH في REST API يمكن أن يساعد المطورين في اتخاذ الخيار الأفضل بناءً على طبيعة التحديث الذي يحتاجون إلى تنفيذه. في منشور المدونة هذا، سنستكشف الفرق بين PUT وPATCH في REST API، مع التركيز على مناقشة PATCH مقابل تحديث REST، ومتى يتم استخدام كل منهما، ونقدم إرشادات حول اختيار الطريقة الصحيحة لحالات الاستخدام المختلفة.
ما هو PUT في REST APIs؟
لفهم الفرق بين PUT وPATCH في واجهات برمجة التطبيقات REST، أولاً، سنحتاج إلى معرفة ما هو PUT في المقام الأول. مرتكز على القسم 9.6 RFC 2616، تطلب طريقة PUT في REST API تخزين الكيان المغلق ضمن عنوان URI للطلب المقدم.
إذا كان عنوان URI للطلب يشير إلى مورد موجود بالفعل، فيجب اعتبار الكيان المرفق بمثابة نسخة معدلة من الكيان الموجود على الخادم الأصلي. إذا كان عنوان URI للطلب لا يشير إلى مورد موجود وكان URI هذا قابلاً للتعريف كمورد جديد بواسطة وكيل المستخدم الطالب، فيمكن للخادم الأصلي إنشاء المورد باستخدام URI هذا.
بمعنى آخر، يتم استخدام أسلوب PUT لتحديث المورد بأكمله على الخادم. وهذا يجعل PUT تحديثًا أكثر اكتمالًا، وغالبًا ما يستخدم عندما يكون الاستبدال الكامل للمورد ضروريًا.
لذا فإن PUT هو الأفضل لحالات الاستخدام التالية:
- تحديث مورد كامل (على سبيل المثال، تحديث ملف تعريف المستخدم بجميع المعلومات الجديدة).
- استبدال عنصر أو سجل بأكمله.
- عندما تكون هوية المورد واضحة، وتحتاج بياناته إلى التحديث بالكامل.
في أنظمة مثل بحث مرن، تعتبر العمليات العاجزة ضرورية لضمان اتساق البيانات. على سبيل المثال، تحديث مستند في Elasticsearch باستخدام PUT يضمن إمكانية تكرار نفس الطلب دون آثار جانبية غير مقصودة.
ما هو التصحيح في REST APIs؟
الآن بعد أن تناولنا PUT في واجهات برمجة تطبيقات REST، دعنا نلقي نظرة على ما هو PATCH في واجهات برمجة تطبيقات REST وكيف يعمل قبل أن نقارن PUT مقابل PATCH في واجهات برمجة تطبيقات REST. كما هو محدد في آر إف سي 5789، تطلب طريقة PATCH في REST API تطبيق مجموعة من التغييرات الموضحة في كيان الطلب على المورد المحدد بواسطة Request-URI.
يتماشى هذا مع التمييز بين PUT vs PATCH REST API، حيث تقوم فقط بإرسال البيانات التي تحتاج إلى تعديل، ويقوم الخادم بتطبيق هذه التغييرات على المورد الموجود دون تغيير المورد بأكمله. غالبًا ما يقوم المطورون بإنشاء تصحيحات لتمثيل هذه التغييرات الإضافية، مما يضمن الحد الأدنى من نقل البيانات والتحديثات الفعالة.
ولهذا السبب فإن طريقة PATCH في REST API مناسبة بشكل أفضل لحالات الاستخدام التالية:
- تحديث مجموعة فرعية فقط من الحقول في أحد الموارد (على سبيل المثال، تغيير عنوان البريد الإلكتروني أو رقم الهاتف الخاص بالمستخدم). يمكن أن يتضمن مثال PATCH API إرسال البريد الإلكتروني الجديد فقط، مع ترك الحقول الأخرى دون تغيير.
- تحسين الأداء عن طريق تقليل حمولة البيانات.
- عندما تريد تحديث أحد الموارد بشكل متزايد بدلاً من استبداله بالكامل.
- قم بإنشاء تصحيحات لتغليف تغييرات حقلية محددة، مثل تعديل البريد الإلكتروني للمستخدم، دون التأثير على البيانات غير ذات الصلة.
لمنصات مثل CMS مقطوعة الرأس التي غالبًا ما تتعامل مع هياكل المحتوى المعقدة، فإن استخدام PATCH للتحديثات الأصغر - مثل تعديل حقل واحد - يمكن أن يقلل من حمل الخادم ويحسن الأداء.
بعد تغطية هاتين الطريقتين، يجب أن تكون لديك فكرة جيدة عن ماهية PUT وPATCH في واجهات برمجة تطبيقات REST. ومع ذلك، قبل أن نصل إلى الفرق بين PUT وPATCH في REST APIs، نحتاج إلى التحدث عن Idempotence في هاتين الطريقتين.
العجز في PUT Vs Patch في REST APIs
في واجهات برمجة تطبيقات REST، يشير العجز إلى خاصية العملية التي تؤدي إلى نفس النتيجة عند تكرارها عدة مرات بنفس المدخلات. وهذا يعني أن تقديم نفس الطلب عدة مرات يجب أن يكون له نفس التأثير على الخادم، بغض النظر عن عدد مرات تنفيذه. يعد هذا أمرًا مهمًا لضمان الاستقرار والقدرة على التنبؤ في واجهة برمجة التطبيقات (API). ولكن ما مدى ارتباطها باختلاف PUT و PATCH في REST API؟
طريقة PUT والعجز
دائمًا ما تكون طريقة PUT في REST API غير فعالة لأنها مصممة لاستبدال المورد بأكمله في URI محدد بالبيانات المقدمة في الطلب. بمعنى آخر، إذا قمت بتنفيذ طلب PUT عدة مرات باستخدام نفس بيانات المورد، فستكون النتيجة هي نفسها دائمًا.
لماذا يعتبر PUT عاجزا؟ عندما تقوم بتقديم طلب PUT، فإنك تخبر الخادم بشكل أساسي، "هذه هي الحالة الكاملة والدقيقة التي أريدها لهذا المورد". سواء قمت بإصدار طلب PUT مرة واحدة أو عدة مرات، فسيكون المورد الناتج متطابقًا دائمًا.
على سبيل المثال، فكر في السيناريو الذي تقوم فيه بتحديث عنوان البريد الإلكتروني للمستخدم. إذا قمت بإجراء نفس طلب PUT عدة مرات، فلن تتغير النتيجة لأنه يتم استبدال المورد بنفس البيانات في كل مرة.
مثال:
| PUT /users/1{"اسم المستخدم": "john_doe"،"البريد الإلكتروني": "[email protected]"} |
إذا قمت بإرسال هذا الطلب عدة مرات، فستكون النتيجة دائمًا هي نفسها:
| {"اسم المستخدم": "john_doe"،"البريد الإلكتروني": "[email protected]"} |
وحتى لو كانت بيانات المستخدم هذه بالفعل، فإن إرسال الطلب مرة أخرى لا يغير شيئًا. يقوم باستبدال البيانات بنفس البيانات، وبالتالي يبقى تأثير الطلب كما هو بغض النظر عن عدد مرات تكراره. وهذا ما يجعل PUT عاجزًا.
طريقة التصحيح والعجز
من ناحية أخرى، فإن طريقة PATCH في REST API غير فعالة بشكل عام أيضًا، ولكن مع المزيد من المرونة. عند إنشاء تصحيحات، تأكد من أن العمليات غير فعالة (على سبيل المثال، تعيين قيمة) لتجنب الآثار الجانبية غير المقصودة من الطلبات المتكررة. يعتمد ما إذا كان PATCH غير فعال على العملية والبيانات التي يتم تعديلها.
لماذا يعتبر PATCH Idempotent؟ بالنسبة لطلبات التصحيح، يعني التكافؤ أن تطبيق نفس التصحيح عدة مرات سيكون له نفس النتيجة. وهذا صحيح طالما أن التصحيح نفسه لا يسبب آثارًا جانبية أو تغييرات إضافية عند تطبيقه بشكل متكرر. إذا واصلت تطبيق نفس التصحيح بنفس البيانات، فيجب أن تظل النتيجة دون تغيير بعد التطبيق الأول.
على سبيل المثال، إذا كنت تقوم فقط بتحديث البريد الإلكتروني للمستخدم، فإن إرسال نفس طلب التصحيح بشكل متكرر لن يغير النتيجة بعد المرة الأولى، حتى لو تم تقديم الطلب عدة مرات. سيظل البريد الإلكتروني للمستخدم كما هو، ولن تتغير حالة المورد.
مثال على واجهة برمجة تطبيقات التصحيح:
| التصحيح /users/1{"البريد الإلكتروني": "[email protected]"} |
إذا كان البريد الإلكتروني هو [email protected] بالفعل، فإن تطبيق هذا التصحيح مرة أخرى لن يؤدي إلى أي تغيير، مما يجعله غير فعال.
ومع ذلك، يمكن أن يكون PATCH أيضًا غير عاجز في بعض الحالات. على سبيل المثال، إذا قامت عملية تصحيح بتعديل عداد أو إضافة عناصر إلى قائمة (مثل زيادة رقم أو إلحاق بمصفوفة)، فقد تؤدي التطبيقات المتكررة لنفس التصحيح إلى نتائج مختلفة. وهذا من شأنه أن ينتهك خاصية العجز الجنسي.
مثال على تصحيح REST لواجهة برمجة التطبيقات غير الفعالة:
| التصحيح / العداد / 1 {"الزيادة": 1} |
إذا قمت بتطبيق هذا التصحيح بشكل متكرر، فسوف يستمر العداد في الزيادة، مما يؤدي إلى قيم مختلفة في كل مرة. هذا ليس عاجزًا لأن النتيجة تتغير مع كل تطبيق.
الآن بعد أن تعرفت على الأساسيات، يمكننا إلقاء نظرة على بعض السيناريوهات النموذجية لفهم الفرق بين PUT وPATCH في REST APIs بشكل أفضل.
سيناريوهات الأمثلة: PUT vs PATCH في REST APIs
بغض النظر عن النظرية، دعونا نلقي نظرة على الفرق بين PUT وPATCH مع الأمثلة، بما في ذلك العمليات العاطلة وغير القادرة.
السيناريو 1: طلب PUT - استبدال المورد بالكامل
تخيل نقطة نهاية API لإدارة المنتجات في نظام التجارة الإلكترونية. يجب عليك تحديث جميع تفاصيل المنتج، بما في ذلك اسمه وسعره ووصفه. يعد هذا مثالًا نموذجيًا لأسلوب HTTP PUT مقابل PATCH، حيث يتم استخدام PUT لاستبدال مورد المنتج الكامل.
المنتج الأولي:
| احصل على /products/1001{"id": 1001,"name": "Laptop":,price": 999.99,description": "كمبيوتر محمول قوي."} |
تريد تحديث سعر المنتج ووصفه. يمكنك إرسال طلب PUT مع المورد بأكمله:
طلب وضع:
| PUT /products/1001{"id": 1001,name": "Laptop":,price": 899.99,description": "كمبيوتر محمول قوي بسعر مخفض."} |
إذا قمت بإجراء طلب PUT هذا مرة واحدة أو عدة مرات، فستكون النتيجة هي نفسها دائمًا. سيتم تحديث تفاصيل المنتج لتعكس السعر والوصف الجديد، وستحدث نفس النتيجة في كل مرة. وهذا يضمن الطبيعة العاجزة لـ PUT.
النتيجة (بعد طلب PUT):
| {"المعرف": 1001،"الاسم": "كمبيوتر محمول"،"السعر": 899.99،"الوصف": "كمبيوتر محمول قوي بسعر مخفض."} |
السيناريو 2: طلب التصحيح – تحديث جزء من المورد
الآن، لنفكر في طلب التصحيح لتحديث جزء فقط من تفاصيل المنتج، مثل الوصف. مثال PATCH API: إذا كنت تريد تغيير وصف المنتج ولكن ليس سعره، فإن PATCH هو الخيار الأفضل. لتنفيذ ذلك، يجب عليك إنشاء تصحيحات تحتوي فقط على الحقول التي تتطلب التعديل، مثل الوصف الموجود في مثال API REST PATCH هذا.
المنتج الأولي:
| احصل على /products/1001{"id": 1001,"name": "Laptop":,price": 999.99,description": "كمبيوتر محمول قوي."} |
طلب التصحيح:
| PATCH /products/1001{"description": "كمبيوتر محمول قوي وخفيف الوزن."} |
عند إرسال طلب التصحيح هذا، سيتم تحديث حقل الوصف فقط. إذا قمت بإرسال نفس طلب التصحيح عدة مرات، فسيظل الوصف دون تغيير بعد التحديث الأول، مما يجعل الطلب غير فعال.
النتيجة (بعد طلب التصحيح):
| {"المعرف": 1001،"الاسم": "كمبيوتر محمول"،"السعر": 999.99،"الوصف": "كمبيوتر محمول قوي وخفيف الوزن."} |
إذا قمت بتطبيق نفس التصحيح مرة أخرى، فسيظل وصف المنتج كما كان بعد التصحيح الأول. والنتيجة متسقة، مما يجعل PATCH غير فعال في هذا السيناريو.
السيناريو 3: طلب التصحيح - عملية غير عاجزة
دعونا نلقي نظرة على عملية التصحيح غير الفعالة. لنفترض أن هناك نقطة نهاية لرصيد محفظة المستخدم، وتريد زيادة الرصيد. يمكن توضيح مثال للفرق بين PUT وPATCH هنا: ستضيف PATCH قيمة إلى الرصيد في كل مرة
المحفظة الأولية:
| الحصول على /users/1/wallet{"id": 1،"الرصيد": 100.00} |
طلب التصحيح:
| التصحيح /users/1/wallet{"increment": 50.00} |
سيؤدي طلب التصحيح هذا إلى زيادة رصيد المحفظة بمقدار 50 دولارًا. إذا قمت بإرسال طلب التصحيح هذا عدة مرات، فسيستمر الرصيد في الزيادة مع كل تصحيح، مما يؤدي إلى نتيجة مختلفة في كل مرة. هذا غير فعال لأن تطبيق نفس التصحيح بشكل متكرر سيؤدي إلى نتيجة مختلفة.
النتيجة (بعد طلب التصحيح الأول):
| {"المعرف": 1،"الرصيد": 150.00} |
النتيجة (بعد طلب التصحيح الثاني):
| {"المعرف": 1،"الرصيد": 200.00} |
هنا، PATCH ليس ضعيفًا لأن الطلبات المتكررة بنفس البيانات تؤدي إلى نتائج مختلفة.
خلاصة: الاختلافات الرئيسية بين PUT وPATCH في REST APIs
يتمثل الاختلاف الرئيسي بين PUT و PATCH في REST API في كيفية التعامل مع التحديثات. يستبدل PUT المورد بأكمله، لذلك يتم مسح أي حقول مفقودة، مما قد يؤدي إلى فقدان البيانات. ولهذا السبب يقوم المطورون بإنشاء تصحيحات للتحديثات الجزئية — لتجنب الكتابة فوق الحقول التي لم تتغير والحفاظ على سلامة البيانات.
وهذا يجعل PATCH أكثر كفاءة للتحديثات الجزئية. مثال PATCH API هو أنه إذا كنت تريد تحديث البريد الإلكتروني للمستخدم فقط، فإن إنشاء التصحيحات لن يؤدي إلا إلى إرسال حقل البريد الإلكتروني، على عكس طلب PUT الذي يتطلب بيانات المستخدم بالكامل.
مع PUT، مطلوب حمولة البيانات الكاملة. وهذا يعني أنه يجب إرسال كل حقل، وسيتم مسح أي حقول مفقودة. ومع ذلك، يقوم برنامج PATCH بإرسال الحقول التي تحتاج إلى التحديث فقط، مما يجعله أكثر كفاءة، خاصة بالنسبة للموارد الكبيرة مع الحد الأدنى من التغييرات. تسمح طريقة PATCH في REST API بطلبات أكثر تركيزًا وأصغر حجمًا، مما يقلل من نقل البيانات.
كل من PUT و PATCH عاجزان. وهذا يعني أن تكرار نفس الطلب سيؤدي إلى نفس النتيجة. ومع ذلك، فإن PUT أكثر قابلية للتنبؤ به لأنه يحل محل المورد بأكمله. التصحيح، عند استخدامه لتعديل الحقول المحددة فقط، قد يؤدي إلى نتائج مختلفة اعتمادًا على كيفية معالجة الخادم للتحديثات.
على سبيل المثال، إذا أدى التصحيح إلى زيادة عداد، فقد تؤدي الطلبات المتكررة إلى نتائج مختلفة. ومع ذلك، يمكن تصميم عمليات PATCH API لتكون غير فعالة أيضًا.
في الختام، فإن الفرق بين PUT وPATCH في REST API يتلخص في طبيعة التحديثات: PATCH مخصص للتغييرات الجزئية، بينما PUT مخصص لاستبدال الموارد بالكامل. كلاهما عاجز، لكن التصحيح يمكن أن يكون أكثر تعقيدًا.
الأفكار النهائية
يعد كل من PUT وPATCH من أساليب HTTP الأساسية في تصميم REST API، لكنهما يخدمان أغراضًا مختلفة، وهو جوهر اختلاف PUT وPATCH في REST API. يمكنك تحسين كفاءة واجهة برمجة التطبيقات (API) ووضوحها ووظيفتها بشكل كبير من خلال فهم الفرق بين PUT وPATCH من خلال الأمثلة التي تناولناها سابقًا في هذه المقالة. ومن خلال اختيار الطريقة الصحيحة (PATCH مقابل Update REST) استنادًا إلى حالة الاستخدام الخاصة بك، يمكنك جعل واجهة برمجة التطبيقات (API) الخاصة بك أكثر كفاءة وقابلة للصيانة وسهلة الاستخدام. ضع في اعتبارك دائمًا طبيعة التحديث، سواء كان كاملاً أو جزئيًا، بالإضافة إلى التأثير على الأداء وتكامل البيانات، وحدد الطريقة التي تتوافق بشكل أفضل مع احتياجاتك.
