REST API: ما هي، طرق HTTP ومبدأ العمل في التطبيقات المحمولة

ما هو REST API؟

REST API (واجهة برمجة تطبيقات نقل الحالة التمثيلية) هو أسلوب معماري اقترحه روي فيلدنغ في أطروحته للدكتوراه في عام 2000. يحدد مجموعة من القيود والمبادئ لتصميم بروتوكولات الشبكة. تسمى واجهة API التي تتوافق مع هذه القيود RESTful. REST ليس بروتوكولًا أو معيارًا — إنه نهج معماري يستخدم البروتوكولات الموجودة (بشكل أساسي HTTP) لتبادل البيانات بين العميل والخادم.

الفكرة الرئيسية لـ REST هي الهندسة الموجهة للموارد. بدلاً من استدعاء الطرق على الخادم (كما في SOAP أو RPC)، يتعامل العميل مع الموارد: يحصل على قوائمها، وينشئ موارد جديدة، ويحدّثها أو يحذفها. كل مورد هو كيان في مجال الموضوع: مستخدم، طلب، منتج، مقالة. للمورد حالة يتم نقلها إلى العميل بتنسيق موحد، عادةً JSON. لا يخزن الخادم حالة العميل بين الطلبات — هذا هو مبدأ stateless، وهو مطلب رئيسي لـ REST.

الخصائص الرئيسية لـ REST API:

• Stateless — كل طلب من العميل يحتوي على جميع المعلومات اللازمة لمعالجته
• Cacheable — يجب وضع علامة واضحة على استجابات الخادم على أنها قابلة للتخزين المؤقت أو غير قابلة
• Layered system — يمكن أن تشمل البنية خوادم وسيطة وموازنات تحميل وبروكسيات
• Uniform interface — واجهة تفاعل موحدة عبر طرق HTTP و URLs ورموز الحالة

مبادئ بنية REST

REST يعتمد على ستة قيود معمارية صاغها فيلدنغ. الامتثال لهذه القيود يضمن قابلية التوسع والأداء وسهولة التكامل. كل مبدأ يحل مشكلة محددة في الأنظمة الموزعة — من الحاجة إلى التخزين المؤقت إلى متطلبات الأمان. دعونا نفحص كل مبدأ بالتفصيل.

مبدأ Uniform Interface يتضمن بالإضافة إلى ذلك أربعة قيود فرعية: تحديد الموارد عبر URI، والتعامل مع الموارد من خلال التمثيلات، والرسائل ذاتية الوصف، و HATEOAS (الوسائط الفائقة كمحرك لحالة التطبيق). غالبًا ما يتم تجاهل القيد الفرعي الأخير في الممارسة العملية — معظم واجهات REST API الحديثة لا تنفذ HATEOAS بشكل كامل، مما يؤدي إلى نقاشات حول ما إذا كانت واجهة API هذه RESTful «حقًا».

مبدأ Stateless هو أحد أهم المبادئ للتوسع. يعني غياب الجلسات على الخادم أن أي مثيل خادم يمكنه معالجة أي طلب. هذا يبسط التوسع الأفقي: ما عليك سوى إضافة خوادم جديدة خلف موازن التحميل. بالنسبة للتطبيقات المحمولة، فإن stateless تعني أيضًا أنه يمكن إرسال الطلب إلى أي خادم CDN، وهو أمر حاسم للتوافر العالمي.

طرق HTTP في REST

كل طريقة HTTP في REST API تتوافق مع عملية محددة على مورد: GET للقراءة، POST للإنشاء، PUT للتحديث الكامل، PATCH للتحديث الجزئي، DELETE للحذف. تعتبر خاصية عدم التغيير (Idempotence) للطرق خاصية رئيسية: GET و PUT و DELETE غير قابلة للتغيير (التنفيذ المتكرر يعطي نفس النتيجة)، بينما POST و PATCH ليستا كذلك. هذا مهم لمعالجة أخطاء الشبكة عندما لا يعرف العميل ما إذا كان الطلب قد وصل إلى الخادم.

• GET — الحصول على مورد أو قائمة موارد. غير قابل للتغيير، لا يغير حالة الخادم
• POST — إنشاء مورد جديد. قابل للتغيير، كل استدعاء ينشئ موردًا جديدًا
• PUT — استبدال كامل للمورد. غير قابل للتغيير، الاستدعاءات المتكررة لا تغير الحالة بعد الأول
• PATCH — تحديث جزئي للمورد. غير قابل للتغيير جزئيًا (يعتمد على التنفيذ)
• DELETE — حذف المورد. غير قابل للتغيير، الحذف المتكرر يُرجع 404 وليس خطأ

رموز حالة HTTP هي جزء لا يتجزأ من REST API. كل رمز يحمل معنى محددًا: 200 OK لـ GET ناجح، 201 Created لـ POST، 204 No Content لـ DELETE بدون نص استجابة، 400 Bad Request للبيانات غير الصالحة، 401 Unauthorized لغياب المصادقة، 404 Not Found لعدم وجود المورد. الاستخدام الصحيح لرموز الحالة يجعل API موثقًا ذاتيًا ويبسط التصحيح.

تنسيقات البيانات: JSON وغيرها

JSON (تدوين كائنات جافا سكريبت) هو التنسيق الرئيسي لنقل البيانات في REST API. ترجع شعبيته إلى البساطة وقابلية القراءة البشرية والدعم الأصلي في JavaScript. يتم نقل JSON مع الرأس Content-Type: application/json. تشمل البدائل XML (كبير الحجم، متقادم) و YAML (مناسب للتكوين، أقل شيوعًا لواجهات API) و Protocol Buffers (ثنائي، فعال للأنظمة عالية التحميل).

يتضمن هيكل كائن JSON في REST API عادةً حقول id و type وسمات المورد. للمجموعات، يتم استخدام مصفوفة JSON مع بيانات وصفية للترقيم. تتبع واجهات REST API الحديثة مواصفات JSON:API (jsonapi.org) أو JSON Schema للتحقق من صحة الاستجابات. استخدام تنسيق بيانات موحد يبسط تطوير مكتبات العميل وتوليد الوثائق.

مثال على استجابة JSON لقائمة المستخدمين:

{
    "data": [
        {
            "id": 1,
            "name": "آنا بيتروفا",
            "email": "anna@example.com"
        }
    ],
    "meta": {
        "total": 42,
        "page": 1,
        "per_page": 10
    }
}

يؤثر اختيار تنسيق نقل البيانات على أداء التطبيق المحمول. يتم ضغط JSON عبر GZIP بنسبة 70-80%، مما يجعله مقبولًا لمعظم السيناريوهات. للتطبيقات في الوقت الفعلي ذات كميات البيانات الكبيرة (البث المباشر، الألعاب)، يُنصح بالانتقال إلى البروتوكولات الثنائية أو استخدام WebSocket مع Protocol Buffers.

أمثلة على طلبات REST API

دعونا نلقي نظرة على أمثلة عملية للعمل مع REST API في جانب التطبيق المحمول. كمثال، لنأخذ واجهة API للعمل مع الطلبات في متجر إلكتروني. لكل طريقة HTTP، يتم عرض الطلب والاستجابة المتوقعة من الخادم. توضح الأمثلة الهيكل النموذجي لـ RESTful API المستخدم في تطوير التطبيقات المحمولة.

GET — الحصول على قائمة الطلبات

طلب للحصول على جميع طلبات المستخدم مع الترقيم. تحتوي الاستجابة على مصفوفة من كائنات الطلب ومعلومات وصفية للتنقل بين الصفحات. يتم تمرير المعلمات page و per_page عبر query string.

// واجهة Retrofit لـ REST API
interface OrderApi {
    @GET("api/v1/orders")
    suspend fun getOrders(
        @Query("page") page: Int = 1,
        @Query("per_page") perPage: Int = 20
    ): Response<OrderListResponse>
}

POST — إنشاء طلب جديد

إنشاء طلب جديد عبر طلب POST. يُرجع الخادم الحالة 201 Created والكائن الذي تم إنشاؤه في نص الاستجابة. مهم: يتم الإنشاء على المجموعة /api/v1/orders، وليس على مورد محدد — هذا هو النمط RESTful القياسي.

@POST("api/v1/orders")
suspend fun createOrder(
    @Body order: CreateOrderRequest
): Response<OrderResponse>

// مثال على نص الطلب
data class CreateOrderRequest(
    val productId: String,
    val quantity: Int,
    val addressId: String
)

DELETE — حذف طلب

يتم حذف المورد باستخدام طريقة DELETE على URL الطلب المحدد. يُرجع الحذف الناجح 204 No Content. خاصية عدم التغيير في DELETE تعني أن الطلب المتكرر لنفس URL يُرجع 404 Not Found، وهو ما يتم معالجته بشكل صحيح على العميل.

@DELETE("api/v1/orders/{id}")
suspend fun deleteOrder(
    @Path("id") orderId: String
): Response<Unit>

// الاستخدام في ViewModel
fun removeOrder(orderId: String) {
    viewModelScope.launch {
        val response = api.deleteOrder(orderId)
        if (response.isSuccessful) {
            showSuccess()
        }
    }
}

توضح هذه الأمثلة تطبيقًا نموذجيًا لـ REST API في جانب Android باستخدام Retrofit و Kotlin Coroutines. لتطبيقات iOS، يؤدي URLSession أو مكتبة Alamofire مع بروتوكولات Codable دورًا مشابهًا. يظل هيكل REST API كما هو بغض النظر عن المنصة — فقط تتغير طريقة تنفيذ الطلبات.

تصميم RESTful API: توصيات عملية

يتطلب تصميم RESTful API عالي الجودة اتباع اتفاقيات تجعل واجهة API بديهية للمطورين. يجب تسمية الموارد بأسماء جمع (/users، /orders، /products)، ويجب أن تعكس طرق HTTP العمليات، ويجب أن تمثل URLs التسلسل الهرمي للتداخل. يجب أن تُرجع الأخطاء JSON موحدًا مع رمز ورسالة، وليس مجرد حالة HTTP. الامتثال لهذه الاتفاقيات يقلل من حاجز الدخول للمطورين الجدد ويبسط التكامل.

• تسمية الموارد — جمع، kebab-case: /api/v1/user-orders، وليس /api/v1/getUserOrders
• التصفية والترتيب — عبر معلمات query: ?status=active&sort=created_at:desc
• الترقيم — قائم على المؤشر للمجموعات الكبيرة، قائم على الصفحة للصغيرة
• الإصدارات — عبر URL (/api/v2/) أو رأس Accept-Version
• الأخطاء — تنسيق موحد: { "error": { "code": "VALIDATION_ERROR", "message": "..." } }
• تحديد المعدل — رؤوس X-RateLimit-Remaining و Retry-After

أحد الأخطاء الشائعة عند تصميم REST API هو التداخل المفرط للموارد. بدلاً من /users/1/orders/5/items/3، من الأفضل استخدام هيكل مسطح مع معلمات query: /items?order_id=5&user_id=1. هذا يبسط التخزين المؤقت، ولا يتطلب الحفاظ على مسارات طويلة على الخادم، وأسهل في التوثيق. كما أن البنية المسطحة أكثر توافقًا مع الاستعلامات القائمة على الرسم البياني عند الانتقال إلى GraphQL في المستقبل.

يتم تنفيذ أمان REST API من خلال المصادقة (JWT، OAuth 2.0) و التفويض على مستوى الموارد. يجب أن يتحقق كل طلب مما إذا كان المستخدم لديه حق الوصول إلى المورد المطلوب. HTTPS إلزامي — بدون تشفير، يتم نقل الرموز والبيانات بنص واضح. للتطبيقات المحمولة، يُنصح باستخدام OAuth 2.0 مع PKCE (Proof Key for Code Exchange) للحصول الآمن على الرموز.

الإصدارات والتخزين المؤقت

الإصدارات في REST API ضرورية للتوافق مع الإصدارات السابقة أثناء التغييرات. أشهر الأساليب: الإصدار في URL (/api/v1/orders)، والإصدار في الرأس (Accept: application/vnd.myapi.v1+json)، والإصدار في معلمة query (?api_version=1). يعتبر إصدار URL الطريقة الأكثر شيوعًا لأنه مرئي بوضوح في السجلات والوثائق. ومع ذلك، فإنه ينتهك مبدأ REST بوجود URL واحد لكل مورد.

التخزين المؤقت في REST API يتم تنفيذه عبر رؤوس HTTP Cache-Control و ETag و Last-Modified. يمكن خدمة طلبات GET المحددة على أنها قابلة للتخزين المؤقت من ذاكرة التخزين المؤقت للمتصفح أو البروكسي دون الاتصال بالخادم. بالنسبة للتطبيقات المحمولة، التخزين المؤقت مهم بشكل خاص — فهو يقلل من استهلاك البيانات ويسرع عرض البيانات المحملة مسبقًا في ظل الاتصال الضعيف. ETag هو تجزئة لمحتوى الاستجابة: يرسله العميل في If-None-Match، ويعيد الخادم 304 Not Modified إذا لم تتغير البيانات.

تشمل البدائل الحديثة لـ REST API GraphQL (جلب بيانات مرن من قبل العميل) و gRPC (بروتوكول ثنائي على HTTP/2 للخدمات المصغرة). ومع ذلك، يظل REST المعيار الرئيسي لواجهات API العامة بسبب بساطته وعموميته ودعمه الواسع للأدوات. يعتمد الاختيار بين REST والبدائل على متطلبات المشروع المحددة: تعقيد الاستعلامات، حجم البيانات، احتياجات التحديثات في الوقت الفعلي.