فهم توثيق YouCan API: دراسة حالة عملية

Recommended resources

The freely available resources this lesson will direct you to.

أهلاً بك في الدرس السابع والأخير من وحدتنا الأولى حول أساسيات الأتمتة وواجهات برمجة التطبيقات (API).

في الدرس السابق، قمنا ببناء فهم عميق لمفهوم المصادقة (Authentication)، وتعرفنا على الفرق الجوهري بين استخدام مفتاح API بسيط وبروتوكول OAuth 2.0 المعقد والآمن. الآن، أنت تعرف "كيف" تحصل على إذن للوصول إلى الـ API. لكن السؤال الذي يطرح نفسه هو: بعد الحصول على الإذن، ما الذي يمكنك فعله بالضبط؟ وكيف تفعله؟

الإجابة على هذه الأسئلة تكمن في "دليل المستخدم" الخاص بكل API، وهو ما يُعرف بـ توثيق الـ API (API Documentation). درس اليوم مخصص لتعلم مهارة أساسية وحاسمة لأي شخص يعمل في مجال الأتمتة: قراءة وفهم توثيق YouCan API كمثال تطبيقي. هذه المهارة هي الجسر الذي سينقلنا من المفاهيم النظرية إلى التطبيق العملي الفعلي على متجرك.

1. ما هو توثيق الـ API؟

ببساطة، توثيق الـ API هو الخريطة التفصيلية التي تصف كل شيء عن واجهة برمجة التطبيقات. بما أن لديك خلفية في الميكاترونيك، يمكنك التفكير في توثيق الـ API كالدليل التقني (Technical Manual) لآلة معقدة. يخبرك هذا الدليل بالمدخلات التي تتوقعها الآلة، والمخرجات التي تنتجها، ومعايير التشغيل، وكيفية التفاعل مع كل جزء منها بأمان.

بدون هذا الدليل، سيكون التفاعل مع الـ API مجرد تخمين وتجربة وخطأ.

عندما تفتح توثيق أي API، هناك مكونات أساسية يجب أن تبحث عنها.

API Documentation Components — المكونات الأساسية التي ستجدها في معظم وثائق الـ API، والتي تشكل خارطة الطريق لفهمها واستخدامها.

للتوضيح أكثر، دعنا نستعرض أهم هذه المكونات.

How to Read API Documentation

هذا المقال بعنوان "How to Read API Documentation" يقدم شرحاً ممتازاً للأجزاء المختلفة التي تشكل توثيق أي API. سنستخدمه كمرجع لفهم هذه الهيكلية.

قم بقراءة الأقسام التالية من المقال (المقال باللغة الإنجليزية، لكن المفاهيم عالمية وستجدها في كل توثيق): Authentication: اقرأه كتذكير سريع لما تعلمناه في الدرس السابق. Resources: ركز على فهم أن الموارد هي "الأسماء" أو الكيانات التي تتعامل معها (مثل المنتجات، الطلبات). API endpoints: افهم أن الـ endpoint هو العنوان (URL) المحدد الذي ترسل إليه طلبك للتفاعل مع مورد معين. Request format: هذا القسم يوضح البيانات التي يجب أن ترسلها في طلبك (Parameters). Response format: يوضح شكل البيانات التي ستستقبلها كرد على طلبك. Response codes: تعلم معنى أشهر أكواد الاستجابة (200, 404, 500) لتعرف هل نجح طلبك أم فشل. الهدف هو التعرف على هذه المصطلحات وفهم دور كل منها.

ملخص سريع للمفاهيم الأساسية:

الموارد (Resources): هي الكيانات أو "الأشياء" التي يمكنك التفاعل معها عبر الـ API. في حالة YouCan، الموارد هي: Product, Order, Customer, إلخ.
نقاط النهاية (Endpoints): هي عناوين URL محددة تستخدمها للوصول إلى الموارد. كل نقطة نهاية تجمع بين فعل (Method) واسم (Resource). مثال: GET /api/products (احصل على المنتجات).
المعلمات (Parameters/Request Body): هي البيانات التي ترسلها مع طلبك لتخصيصه. مثلاً، عند إنشاء منتج جديد (POST /api/products)، ستحتاج إلى إرسال اسمه وسعره ووصفه في جسم الطلب (Request Body).
الاستجابة (Response): هي البيانات التي يعيدها الـ API بعد تنفيذ طلبك، وتكون عادة بصيغة JSON التي تعلمناها سابقاً.
أكواد الحالة (Response Codes): هي أرقام معيارية تشير إلى نتيجة الطلب (e.g., 200 OK للنجاح, 404 Not Found للخطأ).

2. كيف تبدأ بقراءة التوثيق؟ (مثال توضيحي)

قبل أن نغوص في توثيق YouCan، دعنا نشاهد مثالاً عملياً سريعاً لكيفية تنقل المطورين في توثيق جديد.

Webhooks and REST API introduction | مقدمة عن ال Webhooks و ال APIs

هذا الفيديو باللغة العربية يشرح مقدمة عن الـ API ويحتوي على جزء عملي ممتاز يوضح كيفية استكشاف توثيق WooCommerce. مع أن المنصة مختلفة، إلا أن المنهجية المتبعة هي نفسها تماماً.

شاهد من الدقيقة 7:04 إلى 9:08. لاحظ الخطوات التي يتبعها المدرب: يبحث في جوجل عن "WooCommerce API documentation". يفتح التوثيق ويبحث عن قائمة الموارد (Resources) المتاحة. يختار مورداً معيناً (Products). يستعرض الإجراءات (Actions) المتاحة لهذا المورد (Create, List, Update, etc.). يختار إجراءً محدداً (Create a product) ليرى تفاصيله: الـ HTTP Method المطلوب (POST) والـ Endpoint.

هذه العملية المكونة من 5 خطوات هي بالضبط ما سنقوم به الآن مع توثيق YouCan.

3. تطبيق عملي: استكشاف توثيق YouCan API

حان الوقت لتطبيق ما تعلمناه على هدفنا الرئيسي. سنقوم بجولة إرشادية داخل توثيق YouCan الرسمي للمطورين.

Getting started guide | YouCan Developer

هذه هي صفحة البداية الرسمية لتوثيق YouCan API. سنستخدمها كنقطة انطلاق لاستكشافنا.

افتح الصفحة وتصفحها سريعاً. ركز على ثلاثة أشياء رئيسية: API Base URL: عنوان URL الأساسي الذي تبدأ به جميع طلبات الـ API. القائمة على اليسار (Navigation Menu): لاحظ كيف تم تنظيمها حسب الموارد (Entities) مثل Products, Orders, Customers. Postman collection: لاحظ أنهم يوفرون رابطاً لمجموعة Postman جاهزة، وهو أمر مفيد جداً للتجربة والاختبار (سنعود إليه لاحقاً).

الآن، دعنا نحلل التوثيق خطوة بخطوة:

الخطوة 1: تحديد المورد والإجراء (Resource & Action)

تصفح القائمة على يسار صفحة التوثيق. هذه هي قائمة الموارد (Resources) التي يوفرها YouCan API. ستجد فيها كل ما يهمنا: Products, Orders, Customers, Shipping zones وغيرها.

لنفترض أننا نريد "جلب قائمة بجميع المنتجات" من متجرنا.

من القائمة اليسرى، ابحث عن قسم Products.
تحت هذا القسم، ستجد عدة إجراءات (Actions) متاحة مثل:
- Listing (لجلب قائمة)
- Get (لجلب منتج واحد محدد)
- Create (لإنشاء منتج جديد)
- Update (لتحديث منتج موجود)
- Delete (لحذف منتج)

الإجراء الذي نريده هو Listing.

الخطوة 2: تحليل نقطة النهاية (Endpoint)

عندما تضغط على Listing تحت Products، سيأخذك التوثيق إلى صفحة تشرح هذه العملية. (في حالة YouCan، التوثيق متاح بشكل أفضل عبر Postman collection التي أشاروا إليها).

دعنا نفتح رابط مجموعة Postman لـ YouCan API في نافذة جديدة.

في القائمة اليسرى لمجموعة Postman، اذهب إلى Products -> Get all products.
ستجد أن نقطة النهاية (Endpoint) هي:
- Method: GET
- URL: {{baseUrl}}/api/products
هذا يعني أننا سنرسل طلب GET إلى https://api.youcan.shop/api/products لجلب قائمة المنتجات. {{baseUrl}} هو متغير يمثل https://api.youcan.shop.

الخطوة 3: فحص المعلمات والاستجابة (Parameters & Response)

في نفس صفحة Postman، انظر إلى:

Params (Query Params): ستجد معلمات اختيارية يمكنك إضافتها للـ URL لتصفية النتائج، مثل limit (لتحديد عدد المنتجات في الصفحة) أو page (للانتقال بين الصفحات).
Example Response (على اليمين): ستجد مثالاً حياً لشكل بيانات JSON التي ستستقبلها. لاحظ بنيتها: هي عبارة عن مصفوفة (array) data، وكل عنصر داخلها هو كائن (object) يمثل منتجاً له id, name, price, إلخ.

فهم بنية الاستجابة هذه أمر بالغ الأهمية، لأنك عندما تبني نظام أتمتة، ستحتاج إلى معرفة كيفية استخراج المعلومات التي تريدها من هذه البنية (مثلاً، استخراج price لكل منتج).

اختبر فهمك!

باستخدام نفس مجموعة Postman الخاصة بـ YouCan API التي فتحتها:
لنفترض أنك تريد تغيير حالة طلب معين (Order) إلى "مؤكد" (Confirmed).
ما هو المورد، والإجراء، والـ HTTP Method، وشكل الـ URL الذي ستحتاجه على الأرجح؟ وما هي المعلومة الأساسية التي ستحتاج لإرسالها في جسم الطلب (Request Body)؟

أظهر الإجابة

المورد (Resource): Orders.
الإجراء (Action): Update an order status (تحديث حالة الطلب).
HTTP Method: PUT. (يُستخدم PUT أو PATCH عادةً للتحديث).
URL: سيكون شيئاً مثل {{baseUrl}}/api/orders/{id}/status. حيث {id} هو رقم الطلب الذي تريد تحديثه.
جسم الطلب (Request Body): ستحتاج على الأقل لإرسال الحالة الجديدة التي تريد تطبيقها. بالنظر إلى التوثيق، ستجد أن جسم الطلب يجب أن يحتوي على كائن JSON مثل:
```
{
  "status": 1
}
```
حيث 1 يمثل حالة "مؤكد" (Confirmed) حسب توثيق YouCan.

خلاصة الدرس

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

أهم النقاط:

توثيق الـ API هو الدليل التقني الذي يشرح كيفية التفاعل مع واجهة برمجية.
المكونات الأساسية للتوثيق هي: المصادقة، الموارد، نقاط النهاية، المعلمات، وأشكال الاستجابة.
لقراءة التوثيق بفعالية، اتبع الخطوات: حدد المورد والإجراء -> حلل نقطة النهاية (Method + URL) -> افحص المعلمات المطلوبة وشكل الاستجابة المتوقعة.
لقد طبقنا هذه المنهجية بنجاح على توثيق YouCan API، مما جعلنا جاهزين تماماً للخطوة العملية التالية.

الدرس القادم

بهذا الدرس، نكون قد أتممنا الوحدة الأولى بنجاح! لقد بنيت أساساً نظرياً وتقنياً صلباً. الدرس القادم سيكون بداية الوحدة الثانية وبداية العمل الحقيقي. سنتوقف عن الكلام النظري وننتقل إلى التطبيق 100%. سنقوم بـ الوصول إلى YouCan API وتفعيل مفاتيح الوصول الخاصة بمتجرك. بعد هذا الدرس، سيكون لديك مفاتيحك الخاصة، وسترسل أول طلب API حقيقي ومُصادق عليه إلى متجرك مباشرة من Postman. استعد، فالمرحلة العملية على وشك البدء