أفضل ممارسات ترميز عناوين URL في واجهات REST API

لماذا يهم ترميز عناوين URL في واجهات API

يُعدّ الترميز الصحيح لعناوين URL أمرًا بالغ الأهمية في تطوير واجهات REST API. فعناوين URL المُرمَّزة بشكل غير صحيح قد تؤدي إلى طلبات معطوبة، وثغرات أمنية، وفقدان للبيانات، ومشكلات في التوافق بين الأنظمة ولغات البرمجة المختلفة. وبصفتك مطوّر واجهات API، عليك أن تفهم كيفية ترميز عناوين URL عند إرسال الطلبات وكيفية فكّ ترميزها عند معالجة الطلبات.

ترميز معاملات المسار

غالبًا ما تستخدم واجهات REST API معاملات المسار لتحديد الموارد. وعندما تحتوي هذه المعاملات على أحرف خاصة، يصبح الترميز الصحيح ضروريًا:

// معامل مسار يحتوي على أحرف خاصة
// المورد: "Tom & Jerry's Show"
GET /api/shows/Tom%20%26%20Jerry%27s%20Show

// باستخدام JavaScript
const showName = "Tom & Jerry's Show";
const url = `/api/shows/${encodeURIComponent(showName)}`;

// مسار يحتوي على شرطة مائلة أمامية ضمن القيمة
// الملف: "documents/my report.pdf"
GET /api/files/documents%2Fmy%20report.pdf

ترميز معاملات الاستعلام

معاملات الاستعلام هي أكثر المواضع شيوعًا التي تنشأ فيها مشكلات الترميز. قم دائمًا بترميز المفاتيح والقيم على حدٍّ سواء:

// معاملات متعددة تحتوي على أحرف خاصة
GET /api/search?q=C%2B%2B%20programming&category=languages%20%26%20tools&page=1

// باستخدام URLSearchParams (الطريقة المُوصى بها)
const params = new URLSearchParams({
  q: 'C++ programming',
  category: 'languages & tools',
  page: '1'
});
const url = '/api/search?' + params.toString();

التعامل مع المصفوفات والكائنات في سلاسل الاستعلام

تتعامل أُطر عمل واجهات API المختلفة مع معاملات المصفوفات بطرق متباينة. وفيما يلي الأعراف الشائعة:

// مفاتيح مكررة (الأكثر شيوعًا)
GET /api/items?tag=javascript&tag=typescript&tag=react

// صيغة الأقواس (PHP، Rails)
GET /api/items?tags[]=javascript&tags[]=typescript

// مفصولة بفواصل (بعض واجهات REST API)
GET /api/items?tags=javascript,typescript,react

// كائنات متداخلة (صيغة الأقواس)
GET /api/search?filter[status]=active&filter[sort]=date

نوع المحتوى (Content-Type) والترميز

تحدّد ترويسة Content-Type كيفية ترميز بيانات جسم الطلب:

• application/x-www-form-urlencoded - مشابه لسلاسل استعلام URL. تُرمَّز المفاتيح والقيم، وتتحوّل المسافات إلى +
• multipart/form-data - يُستخدم لرفع الملفات. لكل جزء ترميزه الخاص
• application/json - صيغة JSON. لا حاجة لترميز URL للجسم، لكن يجب ضبط ترويسة Content-Type بشكل صحيح

اعتبارات أمنية لواجهات API

• تحقّق دائمًا من معاملات URL المفكوكة ونقّها على الخادم
• انتبه لهجمات اجتياز المسار (path traversal) عبر التسلسلات المُرمَّزة مثل %2e%2e%2f (../)
• طبّق حدودًا على طول عنوان URL لمنع هجمات حجب الخدمة (denial-of-service)
• لا تثِق أبدًا بالترميز الذي يجري على جانب العميل — تحقّق منه دائمًا مجددًا على الخادم
• احذر من هجمات الترميز المزدوج (double-encoding) التي تتجاوز فيها المدخلات الخبيثة عوامل التصفية بعد جولة واحدة من فكّ الترميز
• استخدم الاستعلامات المُعامَلة (parameterized queries) لمنع حقن SQL حتى بعد فكّ ترميز URL

اختبار ترميز عناوين URL في واجهات API

عند اختبار نقاط النهاية (endpoints) لواجهة API الخاصة بك، ضمّن حالات اختبار للسيناريوهات التالية:

• معاملات تحتوي على مسافات (اختبِر كلًّا من %20 و+)
• معاملات تحتوي على أحرف محجوزة (&، =، ?، #)
• معاملات تحتوي على أحرف Unicode
• قيم معاملات فارغة
• قيم معاملات طويلة جدًا
• مدخلات مُرمَّزة مسبقًا (اكتشاف الترميز المزدوج)
• معاملات تحتوي على بايتات فارغة (%00)