بناء طلبات API

لماذا يهم

الطلب المبني خطأً لا يختبر شيئاً، أو يختبر شيئاً آخر. ضع مرشِّحاً (Filter) في جسم طلب GET، وستجد خوادم كثيرة تتجاهله وتعيد القائمة كاملة، فينجح فحص «القائمة تُحمَّل» مع أن المرشِّح لم يُختبر قط. واترك الرمز & دون ترميز داخل عبارة بحث، فيستقبل الخادم معاملين بدلاً من معامل واحد.

والتحكم في كل جزء من الطلب يسهّل أيضاً تحديد العيوب الحقيقية: تغيّر مُدخلاً واحداً في كل مرة، وتعيد إنتاج الخطأ دون واجهة المستخدم، وتسلّم المطورين طلباً يستطيعون تشغيله.

أربعة أماكن يوضع فيها المُدخل

ابدأ من مرجع الواجهة البرمجية. وكثير من الفرق تنشره في صورة مستند OpenAPI، وهو وصف قياسي لواجهة REST تقرؤه الآلة، ويُكتب بصيغة YAML أو JSON. وفيه لكل معامل (Parameter) حقل in يسمّي موضعه، مثل path أو query أو header، ويوصف جسم الطلب تحت requestBody. والمقتطف أدناه هو نقطة النهاية (Endpoint) المستخدمة في المثال التطبيقي.

• معاملات المسار (Path Parameters) تحدد المورد، مثل {customerId} في /customers/{customerId}. وهي مطلوبة دائماً؛ استبدل العنصر النائب كله، بما فيه القوسان.
• معاملات الاستعلام (Query Parameters) تضبط الطلب: التصفية أو الترتيب أو التقسيم إلى صفحات أو البحث أو تشغيل خيار ما. وهي اختيارية غالباً ولها قيمة افتراضية، لذا فإن حذف أحدها حالة اختبار أيضاً. ورمّز المحارف المحجوزة داخل القيم بترميز النسبة (Percent-encoding).
• الترويسات تصف الطلب: Content-Type ما الجسم، وAccept ما تريده في الاستجابة، وAuthorization من المتصل. ولا يدرج OpenAPI هذه الثلاث ضمن المعاملات، بل تحددها requestBody والاستجابات وقسم security.
• جسم الطلب يحمل البيانات التي تنشئها أو تغيّرها. ولا يعطي RFC 9110 المحتوى في طلب GET أو DELETE معنى محدداً بوجه عام، لذا لا يكون لهذين الطلبين جسم في العادة.

# server: https://api.example.com/api/v1
/customers/{customerId}/addresses/{addressId}:
  patch:
    parameters:
      - name: customerId
        in: path
        required: true
        schema: { type: integer }
      - name: addressId
        in: path
        required: true
        schema: { type: integer }
      - name: notify
        in: query
        required: false
        description: Send the customer an SMS about the change
        schema: { type: boolean, default: true }
    requestBody:
      required: true
      content:
        application/json:
          schema: { $ref: '#/components/schemas/AddressChange' }
    responses:
      '200':
        description: The updated address
        content:
          application/json:
            schema: { $ref: '#/components/schemas/Address' }
    security:
      - bearerAuth: []

جرّبها: عارض OpenAPI

جسم الطلب: JSON والنماذج وmultipart

يجب أن تصف ترويسة Content-Type البايتات التي ترسلها فعلاً. وثلاث صيغ تغطي معظم الواجهات البرمجية؛ والمثال يرسل التقييم نفسه بكل منها.

• application/json: الصيغة المعتادة في واجهات REST. تحافظ على الأنواع، فـ4 رقم و"4" نص، وتسمح بتداخل الكائنات والمصفوفات.
• application/x-www-form-urlencoded (معيار WHATWG URL): صيغة نماذج HTML التقليدية، أزواج name=value يربط بينها &، مرمَّزة بترميز النسبة، والمسافة فيها +. وكل القيم فيها نصوص. وبعض نقاط نهاية تسجيل الدخول وإصدار الرموز (Tokens) تشترطها.
• multipart/form-data (RFC 7578): لرفع الملفات. تُفصل الأجزاء بفاصل (Boundary) يُعلَن في Content-Type؛ فاترك العميل يولّده، لأن كتابة multipart/form-data يدوياً بلا الفاصل تجعل الخادم عاجزاً عن تحليل الجسم.
• الصيغة التي لا تقبلها نقطة النهاية يجب أن تُرفض، وعادةً بالرمز 415 Unsupported Media Type، وهذا اختبار سلبي مفيد.

POST /api/v1/stores/riyadh-01/feedback HTTP/1.1
Host: api.example.com
Content-Type: application/json

{"rating": 4, "subscribe": true}

POST /api/v1/stores/riyadh-01/feedback HTTP/1.1
Host: api.example.com
Content-Type: application/x-www-form-urlencoded

rating=4&subscribe=true

POST /api/v1/stores/riyadh-01/feedback HTTP/1.1
Host: api.example.com
Content-Type: multipart/form-data; boundary=x7Kq9

--x7Kq9
Content-Disposition: form-data; name="rating"

4
--x7Kq9
Content-Disposition: form-data; name="photo"; filename="box.jpg"
Content-Type: image/jpeg

(the bytes of the image)
--x7Kq9--

جرّبها: منشئ حمولات API جرّبها: فاحص جسم الطلب

مثال تطبيقي: من العقد إلى الطلب

تقول حالة اختبار: غيّر مدينة العنوان ⁦3⁩ لعميل الاختبار ⁦58⁩ إلى جدة، والرمز البريدي إلى ⁦23436⁩، دون إرسال رسالة SMS إلى العميل. اعمل على المقتطف أعلاه، مُدخلاً بعد مُدخل.

• الطريقة: يعرّف العقد patch لهذا المسار، أي تعديلاً جزئياً.
• المسار: عنوان الخادم، ثم المسار بعد استبدال العنصرين النائبين: /api/v1/customers/58/addresses/3.
• الاستعلام: المعامل notify يرسل رسالة SMS وقيمته الافتراضية true، فحذفه يرسل الرسالة؛ لذا أضف ?notify=false.
• الترويسات: Content-Type: application/json من requestBody، وAccept: application/json من الاستجابة، وAuthorization مع رمز Bearer لحساب اختبار من security.
• الجسم: الحقول المتغيرة فقط، بالأنواع التي يحددها المخطط (Schema). ويشير $ref إلى المخطط AddressChange في موضع آخر من المستند، وهو يعرّف city وpostalCode نصّين، لذا يوضع الرمز البريدي بين علامتي تنصيص: {"city": "Jeddah", "postalCode": "23436"}.
• البدائل: غيّر جزءاً واحداً في كل مرة، كأن ترسل postalCode رقماً، أو تستخدم عنواناً يخص عميلاً آخر، أو تزيل Content-Type، فتشير كل نتيجة إلى مُدخل واحد.

الجزء 1:1PATCH /api/v1/customers/الجزء 2:258/addresses/الجزء 2:23?الجزء 3:3notify=false HTTP/1.1
الجزء 4:4Host: api.example.com
الجزء 5:5Content-Type: application/json
Accept: application/json
الجزء 6:6Authorization: Bearer eyJhbGciOi...

الجزء 7:7{"city": "Jeddah", "postalCode": "23436"}

PATCH /api/v1/customers/58/addresses/3?notify=false HTTP/1.1
Host: api.example.com
Content-Type: application/json
Accept: application/json
Authorization: Bearer eyJhbGciOi...

{"city": "Jeddah", "postalCode": "23436"}

جرّبها: منشئ معاملات استعلام API جرّبها: منشئ ترويسات API

إرسال الطلب من عميل API

عميل API الرسومي، مثل Postman أو أداة «منشئ طلبات API» من Mutqan في المتصفح، يحوّل هذه القرارات إلى حقول: الطريقة، وعنوان URL، وجدول للمعاملات، وجدول للترويسات، وإعدادات التفويض، ومحرر للجسم. أما cURL، وهو عميل يعمل من سطر الأوامر، فيحوّلها إلى خيارات مثل -X و-H و-d. والعادات التالية أهم من الأداة نفسها:

• احفظ عنوان URL الأساسي وحساب الاختبار والرمز (Token) في متغيرات (يكتبها Postman بالشكل {{baseUrl}})، ليعمل الطلب المحفوظ نفسه على كل بيئة.
• أدخل معاملات الاستعلام في الجدول واختر نوع الجسم، ليبني العميل سلسلة الاستعلام ويضبط Content-Type؛ وإن كتبت هذه الترويسة يدوياً أيضاً فتأكد من تطابقهما. والعملاء يختلفون في المحارف التي يرمّزونها، فتحقّق من أن قيمة مثل tea & coffee تصل معاملاً واحداً.
• تحقّق مما أُرسل فعلاً: فالعملاء يضيفون ترويسات لم تكتبها، مثل User-Agent. أرسل الطلب مرة واحدة إلى رابط التقاط (Capture URL) من أداة «فاحص طلبات HTTP» في Mutqan وقارن.
• صدّر الطلب بصيغة cURL لتقارير الأخطاء، مع وضع متغير في سطر الأوامر مثل $TOKEN مكان الرمز (Token). والمثال مكتوب بعلامات التنصيص الخاصة بـbash، وأداة «مولّد أوامر cURL» من Mutqan تكتبه أيضاً لـPowerShell ولـcmd في Windows.
• في cURL يرسل الخيار -d الجسمَ ويجعل الطريقة POST ما لم يحدد -X طريقة أخرى، وبلا ترويسة Content-Type يَسِم الجسم بالنوع application/x-www-form-urlencoded، حتى لو كان JSON.

curl -X PATCH "https://api.example.com/api/v1/customers/58/addresses/3?notify=false" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"city": "Jeddah", "postalCode": "23436"}'

جرّبها: منشئ طلبات API جرّبها: مولّد أوامر cURL جرّبها: فاحص طلبات HTTP

أسئلة شائعة

المراجع

• RFC 9110: HTTP SemanticsIETF · 2022معاني أساليب HTTP وحقول الترويسات ورموز الحالة والتفاوض على المحتوى، بغضّ النظر عن إصدار البروتوكول.
• OpenAPI SpecificationOpenAPI Initiativeالمعيار لوصف واجهات REST: المسارات والعمليات والمعاملات والمخططات والاستجابات وأنظمة الأمان.
• URL StandardWHATWGكيف تحلّل المتصفحات عناوين URL فعلياً وتسلسلها وترمّزها، بما فيها application/x-www-form-urlencoded.
• RFC 7578: Returning Values from Forms: multipart/form-dataIETF · 2015ترميز multipart/form-data المستخدم لرفع الملفات وإرسال النماذج المختلطة.