JSON Patch: الطريقة الذكية لتحديث بيانات API الخاصة بك

لقد قمت ببناء واجهة برمجة تطبيقات (API) حديثة. تقوم `GET` بجلب البيانات، وتقوم `POST` بإنشاء موارد جديدة - سلس حتى الآن. ولكن عندما يتعلق الأمر بتحديث البيانات، تصبح الأمور صعبة.

لنفترض أن المستخدم يريد فقط تغيير بريده الإلكتروني. هل تحتاج حقًا إلى أن يعيد إرسال ملف تعريف المستخدم بالكامل؟ هذا أمر غير عملي وغير فعال وعرضة للأخطاء - خاصة مع الاتصالات البطيئة أو التحديثات المتضاربة.

هناك طريقة أفضل: JSON Patch.
بدلاً من إرسال الكائن بأكمله، فإنك ترسل التغييرات فقط. فكر في الأمر كأنك تعطي خياطًا قائمة بالتعديلات بدلاً من إعادة صنع البدلة بأكملها.

نظرًا لأن JSON أصبح اللغة العالمية لواجهات برمجة التطبيقات، فإن JSON Patch يقدم حلاً خفيف الوزن وأنيقًا للتحديثات الجزئية.

بالطبع، يتطلب تصميم واختبار واجهات برمجة التطبيقات باستخدام JSON Patch الأدوات المناسبة. وهنا يأتي دور Apidog. يتيح لك صياغة واختبار والتحقق من طلبات JSON Patch بسهولة - حتى تعرف أن تحديثاتك تعمل كما هو مقصود قبل كتابة سطر واحد من التعليمات البرمجية. والأفضل من ذلك كله، أنه مجاني للتنزيل والبدء في التجربة اليوم.

💡

هل تريد أداة رائعة لاختبار واجهة برمجة التطبيقات (API) تولد وثائق API جميلة؟

هل تريد منصة متكاملة وشاملة لفريق المطورين لديك للعمل معًا بأقصى إنتاجية؟

يقدم Apidog جميع متطلباتك، ويحل محل Postman بسعر أكثر بأسعار معقولة!

زر

بعد ذلك، دعنا نحلل ما هو JSON Patch، وكيف يعمل، ولماذا يجب أن يكون جزءًا من مشروعك القادم.

المشكلة: طلب PUT "الأعمى"

لفهم سبب فائدة JSON Patch، نحتاج أولاً إلى فهم المشكلة التي يحلها. تقليديًا، يتم تحديث المورد في واجهة برمجة تطبيقات RESTful باستخدام طريقة HTTP PUT.

طلب PUT يهدف إلى أن يكون محايدًا (إجراء نفس الطلب عدة مرات له نفس التأثير مثل إجرائه مرة واحدة) وعادة ما يحل محل المورد بالكامل في عنوان URL المستهدف بالتمثيل الجديد المقدم في نص الطلب.

دعنا نتخيل مورد ملف تعريف المستخدم:

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"
}

الآن، إذا أراد جون فقط تغيير عنوان بريده الإلكتروني، فإن طلب PUT النموذجي سيبدو كالتالي:

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"
}

هل ترى المشكلة؟ كان علينا إرسال كل حقل على حدة، على الرغم من أن 99% من البيانات لم تتغير. لهذا النهج عدة جوانب سلبية:

زيادة عرض النطاق الترددي: نحن نرسل الكثير من البيانات غير الضرورية عبر الشبكة. بالنسبة للموارد الكبيرة، يمكن أن يؤدي ذلك إلى تأثير كبير على الأداء، خاصة على شبكات الهاتف المحمول.
مخاطر أعلى للتعارضات: إذا قامت عملية أخرى بتحديث حقل age بينما يقوم جون بتحرير بريده الإلكتروني email، فإن طلب PUT الخاص بجون قد يقوم عن طريق الخطأ بالكتابة فوق العمر الجديد بالقيمة القديمة التي أرسلها.
تعقيد للعميل: يجب على تطبيق العميل أولاً إجراء GET للمورد بأكمله، وتعديل الحقل المحدد، ثم إجراء PUT للكل مرة أخرى. إنها خطوات متعددة وتتطلب من العميل إدارة الحالة بأكملها.

هنا يأتي دور طريقة HTTP PATCH لإنقاذ الموقف.

الحل: تقديم HTTP PATCH و JSON Patch

تم تقديم طريقة HTTP PATCH للسماح بإجراء تعديلات جزئية على مورد. على عكس PUT، التي تستبدل المورد بأكمله، فإن PATCH تطبق مجموعة من التغييرات على المورد.

ولكن هناك مشكلة: لا يحدد معيار HTTP ما يجب أن يكون عليه تنسيق تلك "التغييرات". يمكنك اختراع تنسيق خاص بك. يمكنك إرسال شيء مثل:

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

ولكن هذا سيكون مخصصًا وغير قياسي، وسيتعين على المطورين الآخرين تعلم لغتك الخاصة.

هذه هي الفجوة التي يملأها JSON Patch. JSON Patch (المعرف في RFC 6902) هو تنسيق موحد لتحديد التغييرات التي سيتم تطبيقها على مستند JSON. يوفر لغة واضحة لا لبس فيها لوصف كيفية تعديل مستند JSON بالضبط.

عندما تجمع بين طريقة HTTP PATCH مع نص منسق كمستند JSON Patch، يكون لديك طريقة قوية ومستندة إلى المعايير لإجراء تحديثات جزئية.

كيف يعمل JSON Patch: الأساسيات

مستند JSON Patch هو دائمًا مصفوفة JSON. كل عنصر في المصفوفة هو كائن عملية. يتم تطبيق هذه العمليات على المستند المستهدف بالترتيب، ويكون التصحيح بأكمله ذريًا، مما يعني أنه إذا فشلت أي عملية واحدة، يتم إجهاض التصحيح بأكمله، ويترك المستند دون تغيير.

يحتوي كل كائن عملية على عضو op إلزامي (اختصار لـ "operation") يحدد الإجراء المراد تنفيذه. العمليات الأكثر شيوعًا هي add، remove، replace، move، و copy.

دعنا ننظر إلى المثال السابق لجون وهو يغير بريده الإلكتروني. باستخدام JSON Patch، يصبح الطلب أبسط بكثير:

PATCH /users/123

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

هذا كل شيء! نحن نرسل عملية واحدة: "استبدل القيمة في المسار '/email' بهذه القيمة الجديدة." الطلب صغير وواضح وموجه بالنية. لا نلمس أي حقل آخر.

فهم خاصية `path`

خاصية path هي مؤشر JSON (RFC 6901)، وهي سلسلة تستخدم بناء جملة قائم على الشرطة المائلة للتنقل عبر مستند JSON إلى القيمة المحددة التي تريد معالجتها.

يشير "/email" إلى حقل email على مستوى الجذر.
يشير "/preferences/theme" إلى حقل theme داخل كائن preferences.
يشير "/firstName" إلى حقل firstName.

هذا البناء قوي للتنقل في هياكل JSON المتداخلة.

JSON Patch مقابل JSON Merge Patch

غالبًا ما يخلط المطورون بين JSON Patch (RFC 6902) و JSON Merge Patch (RFC 7386). دعنا نوضح.

JSON Patch:

يصف تسلسل العمليات.
دقيق للغاية ويسمح بتحديثات معقدة.
مثال: replace, move, copy.

JSON Merge Patch:

يرسل مستند JSON جزئيًا يندمج في الأصل.
أبسط، ولكنه أقل مرونة.
مثال: { "name": "Bob" } سيحل محل حقل الاسم.

باختصار:

استخدم JSON Merge Patch للتحديثات البسيطة والضحلة.
استخدم JSON Patch للعمليات المعقدة أو المتعددة.

عمليات JSON Patch

دعنا نحلل العمليات الأكثر شيوعًا مع الأمثلة. سنستخدم نفس ملف تعريف المستخدم كمستند هدفنا.

1. عملية `add`

تُستخدم عملية add لإدراج قيمة جديدة في كائن أو مصفوفة.

إضافة خاصية جديدة إلى كائن:

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

يضيف هذا حقل twitterHandle جديدًا إلى كائن المستخدم.

إضافة عنصر إلى مصفوفة (في فهرس محدد):

تخيل أن المستخدم لديه مصفوفة "hobbies": ["reading", "cycling"].

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

هذا يدرج "hiking" في الفهرس 1، مما ينتج عنه ["reading", "hiking", "cycling"]. للإضافة إلى نهاية المصفوفة، يمكنك استخدام /-: { "op": "add", "path": "/hobbies/-", "value": "hiking" }.

2. عملية `remove`

تقوم عملية remove بحذف قيمة في موقع محدد.

إزالة خاصية من كائن:

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

هذا يزيل حقل age بأكمله من كائن المستخدم.

إزالة عنصر من مصفوفة:

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

هذا يزيل العنصر الأول (الفهرس 0) من مصفوفة hobbies.

3. عملية `replace`

عملية replace هي في الأساس مزيج من remove و add في نفس المسار. إنها تستبدل القيمة الموجودة في موقع بقيمة جديدة. مثال البريد الإلكتروني الخاص بنا كان replace كلاسيكيًا.

تغيير تفضيل سمة المستخدم:

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

4. عملية `move`

تقوم عملية move بإزالة قيمة من موقع وإضافتها إلى آخر.

نقل قيمة من خاصية إلى أخرى:

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

سيؤدي هذا إلى نقل قيمة firstName إلى خاصية جديدة تسمى first_name وإزالة خاصية firstName القديمة.

5. عملية `copy`

تقوم عملية copy بنسخ قيمة من موقع إلى آخر. تظل القيمة الأصلية دون تغيير.

إنشاء نسخة احتياطية من إعداد:

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

هذا ينسخ قيمة السمة الحالية إلى حقل backupTheme جديد.

6. عملية `test`

هذه ميزة أمان. تتحقق عملية test من أن القيمة في موقع ما تساوي قيمة محددة. إذا فشل الاختبار، يتم إجهاض التصحيح بأكمله. هذا مفيد بشكل لا يصدق لمنع التعارضات (القفل المتفائل).

تأكد من عدم قيام أي شخص آخر بتغيير البريد الإلكتروني قبل تحديثه:

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

إذا لم يكن البريد الإلكتروني email الحالي هو "john.old@example.com" (ربما قامت عملية أخرى بتغييره بالفعل)، تفشل عملية test، ولا تحدث عملية replace أبدًا. هذا يضمن أن تحديثك يستند إلى أحدث حالة معروفة.

لماذا تستخدم JSON Patch؟ الفوائد

الكفاءة: الفائدة الأكثر وضوحًا. أنت ترسل التغييرات فقط، مما يقلل بشكل كبير من حجم الحمولة ويحسن الأداء.
التحكم في التزامن: توفر عملية test آلية مدمجة للقفل المتفائل، مما يساعدك على تجنب التحديثات المفقودة وحالات السباق.
الذرية: تضمن طبيعة "الكل أو لا شيء" لتطبيق التصحيح بقاء بياناتك متسقة. إذا فشلت العملية الخامسة في تصحيح مكون من عشر عمليات، يتم التراجع عن العمليات الأربع الأولى.
الوضوح والنية: يصف نص الطلب بوضوح نية التغيير ("استبدال البريد الإلكتروني"، "إضافة هواية") بدلاً من مجرد تفريغ حالة جديدة. هذا يجعل السجلات أكثر قابلية للقراءة وتصحيح الأخطاء أسهل.
التوحيد القياسي: إنه معيار IETF (RFC 6902). سيتعرف عليه المطورون الآخرون، والعديد من المكتبات والأطر عبر لغات البرمجة المختلفة لديها دعم مدمج لتحليل وتطبيق مستندات JSON Patch.

المزالق والأخطاء الشائعة مع JSON Patch

على الرغم من أن JSON Patch قوي، إلا أن المطورين غالبًا ما يواجهون هذه المشكلات:

استخدام المسار الخاطئ (أخطاء بناء جملة JSON Pointer).
نسيان الحقول المطلوبة مثل value أو from.
تطبيق التصحيحات على مسارات غير موجودة.
الإفراط في استخدام عمليات test بشكل غير صحيح.
الخلط بين JSON Patch و JSON Merge Patch.

لماذا تستخدم واجهات برمجة التطبيقات JSON Patch

تحب واجهات برمجة التطبيقات JSON Patch لأنه:

فعال: يرسل فقط ما تم تغييره.
ذري: تغييرات متعددة في طلب واحد.
مرن: يدعم العمليات المتقدمة مثل move/copy.
موحد: يعمل عبر أنظمة مختلفة.

على سبيل المثال، تدعم واجهة برمجة تطبيقات GitHub JSON Patch لتعديل بيانات تعريف المستودع بكفاءة.

JSON Patch في واجهات برمجة تطبيقات REST

في واجهات برمجة تطبيقات RESTful، غالبًا ما يستخدم JSON Patch مع طريقة HTTP PATCH.

PATCH مقابل PUT:

PUT يستبدل المورد بأكمله.
PATCH يقوم بتحديث جزء من المورد.

مع JSON Patch، يكون Content-Type هو:

application/json-patch+json

يخبر هذا الخادم أن النص يحتوي على مستند JSON Patch.

JSON Patch في GraphQL والبروتوكولات الأخرى

بينما يستخدم JSON Patch بشكل أساسي في واجهات برمجة تطبيقات REST، إلا أنه ذو صلة أيضًا في:

GraphQL mutations: تطبيق تحديثات تدريجية.
gRPC مع حمولات JSON: إرسال تصحيحات منظمة.
البنى القائمة على الأحداث: بث التغييرات فقط بدلاً من الكائنات الكاملة.

كيف يحسن JSON Patch الكفاءة

تخيل تطبيقًا للهاتف المحمول يقوم بمزامنة ملفات تعريف المستخدمين. بدلاً من إعادة تحميل ملف JSON بحجم 2 ميجابايت لكل تحديث صغير، يمكن للتطبيق فقط إرسال طلب تصحيح صغير.

هذا يعني:

أوقات مزامنة أسرع.
استخدام أقل لبيانات الهاتف المحمول.
أداء أفضل للخادم.

التحديات والاعتبارات

JSON Patch قوي، لكنه ليس خالياً من التعقيدات.

تنفيذ معقد على الخادم: تطبيق التصحيح بشكل صحيح على الخادم أكثر تعقيدًا من مجرد قبول كائن JSON جديد. تحتاج إلى التحقق من صحة كل عملية، والتعامل مع المؤشرات إلى مسارات غير موجودة بشكل مناسب، والتأكد من تطبيق التسلسل بأكمله بشكل ذري. لحسن الحظ، تحتوي معظم أطر عمل الويب الحديثة على مكتبات للتعامل مع هذا الأمر نيابة عنك (على سبيل المثال، json-patch لـ Node.js، jsonpatch لـ Python، JsonPatchDocument في .NET).
احتمال حدوث أخطاء: مستند تصحيح مشوه أو مؤشر غير صالح (على سبيل المثال، محاولة replace حقل غير موجود) سيؤدي إلى خطأ. يجب أن تتعامل واجهة برمجة التطبيقات الخاصة بك مع هذه الأخطاء بلطف وتعيد رسائل خطأ واضحة (عادةً 422 Unprocessable Entity أو 400 Bad Request).
ليس حلاً سحريًا: بالنسبة للموارد البسيطة جدًا، قد يكون PUT لا يزال أبسط. يتألق JSON Patch عندما تكون مواردك كبيرة أو عندما تحتاج إلى دعم تحديثات معقدة وشرطية.

اختبار نقطة نهاية JSON Patch باستخدام Apidog

قد يكون اختبار JSON Patch يدويًا أمرًا محبطًا. وهنا تصبح أداة واجهة برمجة تطبيقات متطورة لا تقدر بثمن. يمكن أن يكون Apidog، وهي منصة تطوير واجهة برمجة تطبيقات شاملة، منقذًا كبيرًا هنا:

الاختبار: يمكنك بسهولة اختبار نقطة نهاية PATCH في لوحة تحكم مرئية والحصول على نتائج التحقق من الاستجابة.
الوثائق: يمكنك توثيق نقاط نهاية PATCH الخاصة بك داخل Apidog، مع إظهار التنسيق المتوقع لأعضاء الفريق الآخرين بوضوح، مما يحسن التعاون ويقلل من أخطاء التكامل.

زر

مثال لسير العمل في Apidog:

إنشاء طلب جديد.
تعيين الطريقة إلى PATCH.
إضافة Content-Type: application/json-patch+json.
أدخل مصفوفة JSON Patch الخاصة بك.
إرسال النتائج والتحقق منها على الفور.

باستخدام Apidog، تنتقل من التخمين عما إذا كان التصحيح صحيحًا إلى معرفة أنه تم بناؤه بشكل صحيح، مما يتيح لك تنفيذ واستهلاك واجهات برمجة تطبيقات JSON Patch بثقة والبدء في اختبار JSON Patch كالمحترفين.

أفضل ممارسات JSON Patch

لاستخدام JSON Patch بفعالية:

تحقق من صحة مستندات JSON Patch الخاصة بك قبل الإرسال.
استخدم عمليات الاختبار عندما تكون الاتساق مهمًا.
حافظ على التصحيحات صغيرة لتحقيق الكفاءة.
وثق واجهة برمجة التطبيقات الخاصة بك بوضوح عند استخدام JSON Patch.
استخدم أدوات مثل Apidog لتبسيط الاختبار.

الخاتمة: تبني معيار API أكثر كفاءة

إذن، ما هو JSON Patch؟

إنها طريقة موحدة لوصف التغييرات في مستندات JSON باستخدام عمليات مثل الإضافة والإزالة والاستبدال. بدلاً من إرسال الكائنات الكاملة، يمكنك إرسال التغييرات فقط مما يجعل واجهات برمجة التطبيقات الخاصة بك أكثر كفاءة وموثوقية ومرونة.

يغير JSON Patch طريقة تفكيرنا في تحديث البيانات عبر واجهات برمجة التطبيقات. إنه ينقلنا من الأداة الخام لاستبدال المستندات بالكامل إلى دقة التغييرات الجراحية. من خلال تبني هذا المعيار، نبني واجهات برمجة تطبيقات أكثر كفاءة، وأقل عرضة للتعارضات، وأكثر وضوحًا في نيتها.

بينما يتطلب الأمر مزيدًا من التفكير المسبق على جانب الخادم، فإن الفوائد لتطبيقات العميل وأداء الشبكة كبيرة. في المرة القادمة التي تجد فيها نفسك تصمم نقطة نهاية تحديث، قاوم استخدام PUT الافتراضي واسأل نفسك: "هل يمكن أن يكون هذا عملاً لـ PATCH؟"

بالنسبة للمطورين، يعد فهم JSON Patch أمرًا أساسيًا للعمل مع واجهات برمجة التطبيقات الحديثة، خاصة عند التعامل مع التحديثات الجزئية. وباستخدام أدوات مثل Apidog، يمكنك اختبار طلبات JSON Patch والتحقق منها وتصحيحها بسهولة.

زر