كيف تعمل REST API — رحلة ذهاب وعودة لطلب واحد
كيف تعمل REST API، معروضةً على لوحة تفاعلية: بناء طلب HTTP، والتوجيه والتحقّق على الخادم، والاستجابة التي تُتمّ رحلة الذهاب والعودة.
REST API محادثة بلغة HTTP: العميل يرسل طلباً يسمّي مورداً وإجراءً، والخادم يعالجه، والاستجابة تحمل رمز حالة والنتيجة.
كيف تعمل REST API — رحلة ذهاب وعودة لطلب واحد
لوحة FlowJam التفاعلية لهذا الشرح — كل مسار وصف وسهم أعلاه جزء من مخطط QueryChart حقيقي يمكنك فتحه وتعديله.
كيف تقرأ هذا الشرح المرئي
- اقرأ الأعمدة الثلاثة من اليسار إلى اليمين: الطلب، ومعالجة الخادم، والاستجابة.
- يتناوب صف العميل وصف الخادم، فكل سهم إما العميل يرسل شيئاً وإما الخادم يقرّر شيئاً.
- ويغذّي قرار «هل الطلب صالح؟» إما المسار السليم وإما نقطة نهاية الرفض — وهما النتيجتان اللتان يمكن أن ينتهي إليهما أي استدعاء API.
الطلب
«العميل يبني طلب HTTP (الطريقة، وعنوان URL، والترويسات، والجسم)» هو بداية كل تفاعل REST. فالطريقة هي الفعل — GET يقرأ، وPOST ينشئ، وPUT يستبدل، وPATCH يحدّث، وDELETE يحذف — وعنوان URL يسمّي المورد، فيكون /users/42 هو طلب قراءة مستخدم واحد. و«العميل يرسل الطلب عبر HTTPS» هو النقل: فREST يركب فوق HTTP، وHTTPS يبقي المحادثة خاصة عبر البنية التحتية للإنترنت نفسها التي ترسمها الشروحات المرئية الأخرى.
عمل الخادم
«الخادم يوجّه عنوان URL إلى المعالج المطابق» يربط الطلب بالشيفرة، و«هل الطلب صالح؟» هي البوابة: فالمصادقة (من أنت) والتفويض (هل يُسمح لك) والتحقّق من الحمولة تحدث كلها هنا، وتُرسَل حالات الإخفاق إلى نقطة نهاية الرفض «الخادم يعيد 400 / 401 / 403». أما «المعالج ينفّذ منطق العمل» و«الخادم يقرأ المورد أو يكتبه في قاعدة البيانات» فهما العمل الفعلي — الجزء الذي لا يراه العميل أبداً.
الاستجابة
«الخادم يبني الاستجابة برمز حالة وجسم JSON» هو العقد في صورته الآلية: 200 للنجاح، و201 للإنشاء، و404 للمفقود، و500 لخلل في الخادم. و«العميل يستقبل الاستجابة ويحلّلها» و«العميل يعرض النتيجة للمستخدم» يُكملان الحلقة — فرحلة الذهاب والعودة تنتهي حيث بدأت، عند العميل، وهذا بالضبط سبب عودة الشرح المرئي إلى صف العميل.
العلاقات الرئيسية والخلاصات
- REST عقد بلغة HTTP: الطرق أفعال، وعناوين URL موارد، ورموز الحالة هي النتيجة المقروءة آلياً.
- العميل عديم الحالة — فكل طلب يحمل كل ما يحتاجه الخادم، فلا حاجة إلى جلسة مشتركة.
- التحقّق هو الحد الأمني الفاصل؛ فالطلب غير الصالح يُرفض قبل تنفيذ أي منطق عمل.
- الاستجابة يعرّفها رمز حالتها أولاً وجسمها ثانياً.
- حركة REST تركب DNS وHTTPS والبنية التحتية للإنترنت نفسها التي ترسمها الشروحات المرئية التقنية الأخرى.
متى تستخدم هذا الشرح المرئي
- تعليم المهندسين نموذج الطريقة وعنوان URL ورمز الحالة قبل أن يصمّموا أول نقطة نهاية لهم.
- مراجعة عقد أي API — هل الأخطاء رموز حالة أم 200 مع راية في الجسم؟ — مقابل عرف REST.
- تأسيس نقاش حول التكرار دون أثر إضافي (idempotency) والتخزين المؤقت على الطريقة التي تُبنى بها الطلبات ويُتحقّق منها فعلاً.
كيف تعمل
أسقط نقاط النهاية لديك على مربع الطلب
أضف ملاحظات تُدرج فيها طرقك ومساراتك الحقيقية — GET /orders، وPOST /payments — كي يوثّق المخطط سطح API لديك.
سمِّ رموز الحالة لديك
علّق على خطوة الاستجابة بالرموز التي يعيدها API لديك فعلاً لكل نتيجة، وأضف ما يستخدمه عقدك منها خارج 200 و400.
أضف المصادقة
أدرج خطوة الرمز بين العميل وبوابة التحقّق — رمز JWT أو OAuth في ترويسة Authorization — لتُظهر أين تدخل الهوية إلى الطلب.
ارسم فروع إعادة المحاولة والإخفاق
أضف نقاط نهاية صريحة لإخفاق الشبكة وتحديد المعدّل وأخطاء الخادم، ومع كل واحدة سلوك العميل الذي تطلقه (إعادة المحاولة، أو الانتظار المتزايد، أو حالة الخطأ).
الأسئلة الشائعة
ما هو REST API؟
REST API مجموعة من نقاط نهاية HTTP تكشف موارد نظام ما. ويعمل العملاء على الموارد بطرق HTTP — GET للقراءة، وPOST للإنشاء، وPUT أو PATCH للتحديث، وDELETE للحذف — ويردّ الخادم برمز حالة وبتمثيل للمورد، عادةً بصيغة JSON. وREST أسلوب لا معيار، وقيمته أن أي عميل يتكلّم HTTP يستطيع استخدامه.
ما الفرق بين GET وPOST وPUT وDELETE؟
هي أفعال عقد REST. يقرأ GET مورداً ولا ينبغي أن تكون له آثار جانبية. وينشئ POST مورداً جديداً ويعيد هويته. ويستبدل PUT المورد بالكامل، وهو قابل للتكرار دون أثر إضافي — فتكراره لا يغيّر شيئاً بعد المرة الأولى. ويطبّق PATCH تحديثاً جزئياً. ويزيل DELETE مورداً. والفعل مع عنوان URL يسمّيان معاً الإجراء الكامل، ولهذا يُبرز مربع الطلب في الشرح المرئي الطريقة أولاً.
لماذا رموز الحالة مهمة في REST؟
لأنها النتيجة المقروءة آلياً للطلب. فالعميل يستطيع التفرّع بناءً على رمز الحالة دون تحليل الجسم: 2xx نجاح، و4xx خطأ من العميل، و5xx خطأ من الخادم. وواجهات API التي تعيد 200 مع راية خطأ في الجسم تكسر هذا العقد وتجبر كل عميل على معالجة الاستجابة معالجة خاصة.
ما الذي يجعل أي API متوافقاً مع REST؟
القائمة العملية: موارد مسمّاة بعناوين URL، وإجراءات معبَّر عنها بطرق HTTP، وطلبات عديمة الحالة (كل طلب يحمل كل ما يحتاجه الخادم)، واستجابات تستخدم رموز الحالة استخداماً سليماً، وغالباً روابط تشعّبية أو عناوين URL موسومة بالإصدار. وتنمذج اللوحة رحلة الذهاب والعودة — الطلب، والتحقّق، والمعالجة، والاستجابة — وهي الشكل الذي يشترك فيه كل تبادل متوافق مع REST.
عدّل هذا الشرح المرئي في QueryChart (FlowJam)
افتح لوحة REST هذه نفسها كمخطط خاص بك، وأعد تسمية العميل والخادم بأسماء خدماتك، وعلّق على نقاط النهاية لديك.