لا تفوت الفرصة—انضم إلى آلاف المطورين الذين يثقون في Apidog لتلبية احتياجاتهم من واجهات برمجة التطبيقات. قم بالتنزيل الآن واختبر الفرق في تطوير واجهات برمجة التطبيقات واختبارها وتوثيقها بسعر أكثر معقولية بكثير!
زر
ربما احتجت بالفعل إلى استدعاء واجهة برمجة تطبيقات (API) خارجية في بعض المشاريع، أو أنك تتعلم كيفية جعل الأنظمة المختلفة تتواصل مع بعضها البعض. عندما ترسل طلبًا وفقًا للوثائق، غالبًا ما تتلقى استجابات خطأ غير مفهومة: 400 طلب سيء (Bad Request)، 401 غير مصرح به (Unauthorized)، أو ببساطة لا يتم إرجاع أي شيء.
غالبًا ما تكمن المشكلات في بعض التفاصيل التي تبدو بسيطة ولكنها في الواقع حاسمة: تنسيق طلب غير صحيح، معلومات رأس (Header) ضرورية مفقودة، طريقة مصادقة غير صحيحة، أو عدم تطابق تنسيق البيانات مع ما تتوقعه واجهة برمجة التطبيقات. إذا لم يتم فهم هذه المفاهيم الأساسية بوضوح، فإن كل استدعاء لواجهة برمجة التطبيقات يبدو وكأنه مقامرة.
تحتاج إلى فهم حقيقي لكل مكون من مكونات الطلبات والاستجابات ومعرفة أدوارها، حتى تتمكن من تحديد السبب بسرعة عند ظهور المشكلات.
بعد ذلك، سنبدأ من المفاهيم الأساسية خطوة بخطوة لتوضيح العملية الكاملة لتفاعلات واجهة برمجة التطبيقات.
الطلبات: ما تقوله للخادم
عندما تريد الحصول على معلومات من الخادم أو جعل الخادم يقوم بعملية ما، تحتاج إلى إرسال طلب.
يتضمن طلب واجهة برمجة التطبيقات الكامل عدة عناصر رئيسية. أولها هو طريقة الطلب، والأكثر شيوعًا هي GET، POST، PUT، DELETE.
- تُستخدم GET لاسترداد البيانات؛
- تُستخدم POST لإنشاء بيانات جديدة؛
- تُستخدم PUT لتحديث البيانات الموجودة؛
- تُستخدم DELETE لحذف البيانات.
بالإضافة إلى الطريقة، يحتاج الطلب إلى تحديد عنوان URL، والذي يخبر النظام بمكان المورد المحدد الذي تريد الوصول إليه. على سبيل المثال، https://api.weather.com/current/beijing يشير بوضوح إلى أنك تريد الحصول على معلومات الطقس الحالية لبكين.
لكن مجرد وجود الطريقة وعنوان URL ليس كافيًا؛ فغالبًا ما تحتاج إلى تمرير المزيد من المعلومات إلى الخادم. وهنا يأتي دور الأجزاء الأخرى من الطلب: الرأس (Header) والجسم (Body).
الرأس (Header): تعليمات إضافية للطلب
يحتوي الرأس (Header) على بيانات وصفية مختلفة حول الطلب، مما يساعد الخادم على فهم طلبك ومعالجته بشكل أفضل.
الرأس الأساسي (Header) هو Content-Type، والذي يخبر الخادم بتنسيق البيانات التي ترسلها. إذا كنت ترسل بيانات JSON، فاضبط Content-Type: application/json. إذا كنت ترسل بيانات نموذج، فاضبط Content-Type: application/x-www-form-urlencoded.
رأس (Header) آخر مهم هو User-Agent، والذي يحدد العميل الذي يرسل الطلب. تقوم المتصفحات تلقائيًا بتعيين هذه القيمة، لإخبار الخادم ما إذا كان الطلب من Chrome أو Firefox أو متصفح آخر.
يخبر رأس (Header) Accept الخادم بالتنسيق الذي تتوقعه للاستجابة. على سبيل المثال، Accept: application/json يعني أنك تريد من الخادم إرجاع البيانات بتنسيق JSON.
هناك أيضًا رؤوس (Headers) للتحكم في التخزين المؤقت، مثل Cache-Control، والتي يمكن أن توجه الخادم أو خوادم الوكيل الوسيطة حول كيفية التعامل مع التخزين المؤقت. قد تبدو هذه الرؤوس تقنية، ولكن فهمها يساعدك على التحكم بشكل أفضل في سلوك واجهة برمجة التطبيقات.
الجسم (Body): المحتوى المحدد للطلب
عندما تحتاج إلى إرسال كمية كبيرة من البيانات إلى الخادم، فإن تلك البيانات توضع في الجسم (Body).
عادةً لا تحتوي طلبات GET على جسم (Body)، حيث تُستخدم GET بشكل أساسي لاسترداد البيانات، ويمكن وضع المعلمات المطلوبة مباشرة في عنوان URL. لكن طلبات مثل POST و PUT غالبًا ما تحتاج إلى جسم (Body) لحمل البيانات.
تنسيق الجسم (Body) الأكثر شيوعًا هو JSON. على سبيل المثال، عند تسجيل مستخدم على موقع ويب، يرسل متصفحك طلب POST مع جسم (Body) قد يبدو كالتالي:
{
"username": "john_doe",
"email": "john@example.com",
"password": "secretpassword"
}
تنسيق جسم (Body) آخر شائع هو form-data، خاصة عند تحميل الملفات. يمكن أن يتضمن هذا التنسيق بيانات نصية وبيانات ملفات، مما يجعله مثاليًا للتعامل مع عمليات إرسال النماذج المعقدة.
تستخدم بعض واجهات برمجة التطبيقات تنسيق XML للجسم (Body)، على الرغم من أنه أقل شيوعًا الآن من JSON، إلا أنه لا يزال يستخدم على نطاق واسع في بعض أنظمة الشركات. بغض النظر عن التنسيق، فإن المفتاح هو التأكد من أن رأس (Header) Content-Type يطابق التنسيق الفعلي للجسم (Body).
الاستجابات: رد الخادم عليك
عندما يتلقى الخادم طلبك، فإنه يعيد استجابة. يشبه هيكل الاستجابة هيكل الطلب، بما في ذلك الرأس (Header) والجسم (Body)، ولكن مع عنصر إضافي مهم: رمز الحالة (status code).
رمز الحالة هو رقم مكون من ثلاثة أرقام يخبرك بنتيجة معالجة الطلب. 200 يشير إلى النجاح، وهو ما تأمل أن تراه غالبًا. 404 يعني أن المورد المطلوب لم يتم العثور عليه، وهو "خطأ 404" الشهير. 500 يشير إلى خطأ داخلي في الخادم، مما يعني عادةً أن شيئًا ما حدث خطأ على جانب الخادم.
يحتوي رأس (Header) الاستجابة على معلومات مختلفة حول الاستجابة. يخبرك Content-Type بتنسيق بيانات الاستجابة، ويخبرك Content-Length بحجم بيانات الاستجابة، ويُستخدم Set-Cookie لتعيين ملفات تعريف الارتباط (cookies) على العميل.
يحتوي جسم (Body) الاستجابة على البيانات الفعلية التي طلبتها. إذا كنت تطلب معلومات الطقس، فقد يتضمن الجسم درجة الحرارة والرطوبة وسرعة الرياح وما إلى ذلك. إذا كنت تطلب معلومات المستخدم، فقد يتضمن الجسم اسم المستخدم والبريد الإلكتروني ووقت التسجيل وما إلى ذلك.
يساعدك فهم هيكل الاستجابة على تحديد ما إذا كان استدعاء واجهة برمجة التطبيقات ناجحًا وكيفية التعامل مع البيانات المعادة. عندما تسوء استدعاءات واجهة برمجة التطبيقات، فإن التحقق من رمز الحالة وجسم (Body) الاستجابة عادة ما يكون الخطوة الأولى في تشخيص المشكلات.
المصادقة (Auth): إثبات هويتك
تتطلب معظم واجهات برمجة التطبيقات القيمة شكلاً من أشكال المصادقة. تمامًا كما تحتاج إلى بطاقة هوية لدخول أماكن معينة، تحتاج إلى تقديم بيانات اعتماد للوصول إلى واجهات برمجة التطبيقات المحمية.
أبسط طريقة مصادقة هي مفتاح API (API Key). يمنحك مزود الخدمة مفتاحًا فريدًا، والذي تقوم بتضمينه في كل طلب. توضع مفاتيح API عادةً في الرأس (Header)، مثل Authorization: Bearer your-api-key-here.
طريقة أخرى شائعة هي المصادقة الأساسية (Basic Authentication). تقوم بتقديم اسم مستخدم وكلمة مرور، يقوم العميل بترميزهما ووضعهما في رأس (Header) Authorization. على الرغم من بساطتها، إلا أن هذه الطريقة تتمتع بأمان منخفض نسبيًا.
OAuth هي طريقة مصادقة أكثر تعقيدًا ولكنها آمنة. تسمح للمستخدمين بتفويض تطبيقات الطرف الثالث بالوصول إلى بياناتهم دون تقديم كلمات مرور مباشرة. عندما تسجل الدخول إلى تطبيقات أخرى باستخدام WeChat، فإنك تستخدم عملية OAuth.
JWT (JSON Web Token) هي طريقة مصادقة شائعة أخرى. بعد تسجيل دخول المستخدم، يقوم الخادم بإنشاء رمز (token) يحتوي على معلومات المستخدم، والذي يحمله المستخدم في الطلبات اللاحقة. فائدة JWT هي أن الخادم لا يحتاج إلى تخزين معلومات الجلسة، مما يحسن قابلية توسيع النظام.
يعتمد اختيار طريقة المصادقة على احتياجاتك ومتطلبات الأمان الخاصة بك. بالنسبة للمشاريع الشخصية البسيطة، قد يكون مفتاح API كافيًا. أما بالنسبة للتطبيقات التي تتطلب تسجيل دخول المستخدم، فقد يكون OAuth أو JWT أكثر ملاءمة.
تطبيق عملي: ربط هذه المفاهيم معًا
الآن دعنا نرى كيف تعمل هذه المفاهيم معًا من خلال مثال محدد. افترض أنك تقوم بتطوير تطبيق مدونة وتحتاج إلى إنشاء مقال جديد.
أولاً، ترسل طلب POST إلى https://api.myblog.com/articles. يتضمن رأس (Header) الطلب Content-Type لتحديد تنسيق البيانات و Authorization لتقديم معلومات المصادقة:
POST /articles HTTP/1.1
Host: api.myblog.com
Content-Type: application/json
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...
يحتوي الجسم (Body) على المحتوى المحدد للمقال:
{
"title": "API Basics Introduction",
"content": "This is a detailed introduction to APIs...",
"tags": ["API", "Programming", "Beginner"]
}
بعد استلام الطلب، يقوم الخادم أولاً بالتحقق من الرمز (token) في رأس (Header) Authorization للتأكد من أن لديك إذنًا بإنشاء المقالات. ثم يقوم بتحليل بيانات JSON في الجسم (Body) وإنشاء سجل مقال جديد.
إذا سارت الأمور بسلاسة، يعيد الخادم رمز الحالة 201 (مما يشير إلى الإنشاء الناجح). قد يتضمن رأس (Header) الاستجابة موقع المقال الذي تم إنشاؤه حديثًا، ويحتوي الجسم (Body) على معلومات المقال الكاملة، بما في ذلك المعرف الذي تم إنشاؤه بواسطة النظام ووقت الإنشاء:
{
"id": 12345,
"title": "API Basics Introduction",
"content": "This is a detailed introduction to APIs...",
"tags": ["API", "Programming", "Beginner"],
"created_at": "2024-01-15T10:30:00Z",
"author_id": 678
}
توضح هذه العملية الكاملة كيف تعمل الطلبات والاستجابات والجسم (Body) والرأس (Header) والمصادقة (Auth) معًا. لكل جزء دور خاص به، لكنها تكمل معًا تفاعل API كامل.
تصحيح الأخطاء والاختبار: جعل تطوير API أكثر سلاسة
عندما تبدأ في استخدام واجهات برمجة التطبيقات فعليًا، ستواجه حتمًا مشكلات مختلفة. يتم إرسال الطلب، ولكنه يعيد رمز حالة خطأ؛ أو تنسيق بيانات الاستجابة ليس كما توقعت؛ أو تفشل المصادقة دائمًا.
في هذه المرحلة، تحتاج إلى أن تكون قادرًا على عرض محتوى الطلب والاستجابة بالكامل. تعد أدوات المطور في المتصفح نقطة بداية جيدة، حيث يمكنها عرض جميع طلبات HTTP، بما في ذلك الرأس (Header) والجسم (Body). لاختبار API أكثر تعقيدًا، سيكون استخدام Apidog للعمل أكثر فائدة.
تشمل المشكلات الشائعة عدم تطابق Content-Type، وأخطاء معلومات المصادقة، وتنسيقات الطلبات غير الصحيحة، وما إلى ذلك. يساعد التحقق الدقيق من رمز الحالة ورسائل الخطأ عادةً في تحديد المشكلة بسرعة.
زر