ما هو طلب PUT في واجهة برمجة التطبيقات (الدليل الأحدث لعام 2026)

في هذه المقالة، سنتحدث عن كل ما تحتاج لمعرفته حول API وطلبات PUT. سنبدأ بشرح ما هو API ثم نتعمق في ما هي طلبات PUT وكيف تختلف عن طرق HTTP الأخرى مثل POST.

سنقدم لك بعض الممارسات المثلى وصيغ الاستجابة الشائعة لـ API، وسنوضح لك كيفية إجراء طلب PUT في Apidog.

لذا، دون مزيد من التأخير، دعنا نتعمق في عالم API وطلبات PUT!

ما هو API؟

API، أو واجهة برمجة التطبيقات، هو مجموعة من القواعد المحددة التي تمكّن التطبيقات المختلفة من التواصل مع بعضها البعض. إنه مثل النادل الذي يأخذ طلبك وينقله إلى المطبخ ثم يجلب لك طعامك. تساعد APIs مكونات البرمجيات المختلفة في التواصل ونقل البيانات بسهولة وأمان. إنها مثل الصلصة السرية التي تجعل تطوير البرمجيات والابتكار أكثر بساطة وكفاءة.

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

باختصار، APIs هي مثل الصمغ الذي يمسك بمكونات البرمجيات المختلفة معًا، مما يمكّنها من العمل بسلاسة وكفاءة.

ما هي طلبات PUT؟

طلب PUT هو طريقة طلب HTTP تُستخدم لتحديث أو استبدال مورد موجود على الخادم. يقوم طلب PUT بإنشاء مورد جديد أو استبدال تمثيل المورد المستهدف بحمولة الطلب.

الطلب له جسم والاستجابة الناجحة بها جسم. طلب PUT ليس آمناً وهو متطابق. لا يُسمح به في نماذج HTML. إليك مثال على طلب PUT:

PUT /new.html HTTP/1.1
Host: example.com
Content-type: text/html
Content-length: 16

<p>ملف جديد</p>

إذا لم يكن للمورد المستهدف تمثيل حالي وقام طلب PUT بإنشاء واحد بنجاح، يجب على الخادم الأصلي إبلاغ وكيل المستخدم عن طريق إرسال استجابة 201 (تم الإنشاء). إذا كان للمورد المستهدف تمثيل حالي وتم تعديل ذلك التمثيل بنجاح وفقًا لحالة التمثيل الم enclosed، يجب على الخادم الأصلي إرسال إما استجابة 200 (حسناً) أو 204 (لا محتوى) للإشارة إلى اكتمال الطلب بنجاح.

كيف يعمل طلب PUT؟

عندما تقوم بإجراء طلب HTTP PUT، ويشير Request-URI إلى مورد موجود، يقوم الخادم باستبدال ذلك المورد تمامًا بالبيانات الموجودة في جسم طلب PUT. إذا كان Request-URI لا يشير إلى مورد موجود، يمكن للخادم إنشاء المورد باستخدام ذلك URL.

طلبات PUT مقابل طلبات POST

الفرق بين طلب PUT وطلب POST هو أن طلب PUT هو متطابق، مما يعني أن استدعاءه مرة واحدة أو عدة مرات متعاقبة له نفس التأثير (أي لا تأثير جانبي)، بينما قد تؤدي طلبات POST المتطابقة المتعاقبة إلى تأثيرات إضافية، تشبه وضع الطلب عدة مرات. تُستخدم طلبات PUT لتحديث أو استبدال مورد موجود على الخادم، بينما تُستخدم طلبات POST لإضافة مورد على الخادم.

كيفية إرسال طلب PUT في API

لإرسال طلب PUT في API، تحتاج إلى تحديد طريقة HTTP كـ PUT وعنوان URL للمورد الذي تريد تحديثه أو استبداله. تحتاج أيضًا إلى تضمين التمثيل المحدث للمورد في حمولة الطلب. إليك مثال على طلب PUT في Python باستخدام مكتبة requests:

import requests

url = 'https://example.com/api/resource/1'
data = {'key': 'value'}

response = requests.put(url, json=data)

في هذا المثال، ترسل طريقة requests.put() طلب PUT إلى عنوان URL المحدد مع التمثيل المحدث للمورد في معلمة data. يتم تخزين الاستجابة من الخادم في متغير response.

إنشاء واختبار طلب PUT في Apidog

Apidog هي منصة تعاون متكاملة لوثائق API، وتصحيح API، وتوليد API، واختبار API التلقائي تجمع بين Postman وSwagger وMock وJMeter لحل مشكلة التزامن البيانات بين الأنظمة المختلفة باستخدام مجموعة من الأنظمة ومجموعة من البيانات.

إنها منصة تعاون شاملة لـ API توفر وثائق API، وتصحيح API، وتوليد API، واختبار API التلقائي. مع نظام واحد وبيانات مركزية، تحل Apidog مشكلة تزامن البيانات عبر أنظمة متعددة. بمجرد تعريف وثيقة API، يمكن استخدام تصحيح API، وتوليد البيانات، واختبار API مباشرة بدون الحاجة إلى إعادة التعريف.

لإنشاء واختبار طلب PUT في Apidog، يمكنك اتباع هذه الخطوات:

1. فتح Apidog: افتح Apidog واصنع طلبًا جديدًا.

2. حدد طريقة HTTP: اختر PUT كطريقة HTTP.

3. حدد عنوان URL للطلب: أدخل عنوان URL للمورد الذي تريد تحديثه، وأضف رؤوس الطلب، و/أو جسم الطلب. ثم انقر على زر "إرسال" لإرسال طلب PUT.

4. تحقق من الاستجابة: تحقق من الاستجابة من الخادم للتأكد من أن طلب PUT كان ناجحًا.

أفضل الممارسات لاستخدام طلبات PUT في API

إليك بعض الممارسات المثلى لاستخدام طلبات PUT في API:

1. استخدم صيغة استجابة متناسقة: من الجيد استخدام صيغة استجابة متناسقة لجميع نقاط النهاية الخاصة بك، بما في ذلك طلبات PUT. يمكن أن يسهل ذلك على العملاء فهم والتعامل مع API الخاصة بك.
2. تأكد من أن التحديثات متطابقة: العمليات المتطابقة هي تلك التي يمكن تكرارها عدة مرات دون التسبب في آثار غير مقصودة. طلبات PUT هي متطابقة، مما يعني أن استدعاءها مرة واحدة أو عدة مرات متعاقبة له نفس التأثير. وذلك لأن حمولة الطلب تحتوي على التمثيل المحدث للمورد. إذا كان المورد غير موجود، يتم إنشاء مورد جديد بالتمثيل المحدد.
3. نظم تصميم API حول الموارد: تم تصميم REST APIs حول الموارد، وهي أي نوع من الكائنات أو البيانات أو الخدمات التي يمكن أن يصل إليها العميل. للمورد معرف، وهو URI يحدد المورد بشكل فريد. على سبيل المثال، قد يكون URI لطلب عميل معين: https://example.com/orders/1.
4. حدد عمليات API من حيث طرق HTTP: تستخدم REST APIs طرق HTTP القياسية لأداء العمليات على الموارد. تشمل العمليات الأكثر شيوعًا GET وPOST وPUT وPATCH وDELETE. تُستخدم طلبات PUT لتحديث أو استبدال مورد موجود على الخادم، بينما تُستخدم طلبات POST لإضافة مورد على الخادم.
5. توافق مع دلالات HTTP: يجب أن تتوافق REST APIs مع دلالات HTTP. على سبيل المثال، يجب استخدام طلبات PUT لتحديث أو استبدال مورد موجود، بينما يجب استخدام طلبات POST لإضافة مورد على الخادم. يساعد ذلك في ضمان أن تكون API الخاصة بك متسقة وسهلة الاستخدام.

بعض صيغ الاستجابة الشائعة من طلب PUT

تعتمد صيغة الاستجابة لطلب PUT على تصميم API وحالة الاستخدام المحددة. ومع ذلك، من الجيد استخدام صيغة استجابة متناسقة لجميع نقاط النهاية الخاصة بك، بما في ذلك طلبات PUT. إليك بعض صيغ الاستجابة الشائعة لطلبات PUT:

1. رمز حالة HTTP 200 OK: يتم إرجاع هذا الرمز لحالة ناجحة لطلب PUT لتحديث مورد موجود. لا حاجة لجسم استجابة. رمز حالة HTTP 204 لا محتوى هو حتى أكثر ملاءمة.
2. رمز حالة HTTP 201 تم الإنشاء: يتم إرجاع هذا الرمز لحالة ناجحة لطلب PUT لمورد جديد، مع عنوان URI الأكثر تحديدًا للمورد الجديد المعاد في حقل رأس الموقع وأي URIs وبيانات تعريف أخرى ذات صلة بالمورد تعكس في جسم الاستجابة.
3. رمز حالة HTTP 409 تعارض: يتم إرجاع هذا الرمز لطلب PUT لم يكن ناجحًا بسبب تعديل طرف ثالث، مع قائمة بالاختلافات بين التحديث المحاول والمورد الحالي في جسم الاستجابة.
4. رمز حالة HTTP 400 طلب غير صالح: يتم إرجاع هذا الرمز لطلب PUT لم يكن ناجحًا، مع نص باللغة الطبيعية (مثل الإنجليزية) في جسم الاستجابة يشرح لماذا فشل طلب PUT.

الخلاصة

في هذه المقالة، تعلمنا عن PUT، وهي طريقة HTTP تُستخدم لإنشاء أو تحديث مورد على خادم. تُستخدم لتحديث السجل الموجود، وإذا لم يكن السجل موجودًا، فإنها تنشئ واحدًا جديدًا. الفرق الأساسي بين طلبات POST وPUT ينعكس في معاني مختلفة لـ Request-URI.

عند تصميم API، من المهم استخدام الطريقة الصحيحة بناءً على الكائن الذي تشير إليه في الطلب. إذا كنت تسمي URL للكائنات التي أنشأتها بشكل صريح، فلا تتردد في استخدام PUT.

بالإضافة إلى ذلك، تعلمنا كيفية إنشاء واختبار APIs باستخدام مجموعة أدوات تطوير API من Apidog. تتيح لك هذه المجموعة تصميم وتطوير APIs بشكل أسرع وبالعمل معًا. 🚀