تصميم API: REST مقابل GraphQL مقابل gRPC — كيف تختار

كل تطبيق حديث يتحدث إلى تطبيقات أخرى عبر APIs. لم يعد السؤال ما إذا كنت ستبني API، بل أي نمط من API ستبني. REST كان الخيار الافتراضي لأكثر من عقد. GraphQL ظهر كرد على جمود REST. gRPC يأخذ نهجاً مختلفاً تماماً مبني على HTTP/2 وبروتوكولات المخازن المؤقتة. الاختيار بينها يتطلب فهم ليس فقط البناء، بل فلسفة التصميم الأساسية التي يمثلها كل منها.

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

REST: تصميم موجه للموارد يفهمه الويب

REST — نقل الحالة التمثيلي — ليس بروتوكولاً. إنه نمط معماري حدده روي فيلدينغ في أطروحته للدكتوراه عام 2000. الفكرة الأساسية هي أنك تصمم مجالك كموارد، كل منها محدد بعنوان URL، وتتعامل مع تلك الموارد من خلال مجموعة موحدة من أفعال HTTP: GET وPOST وPUT وPATCH وDELETE.

تصميم REST الجيد هو تصميم موجه للموارد. أنت لا تصمم نقاط نهاية حول الأفعال — تصمم نقاط نهاية حول الأسماء. بدلاً من /createUser أو /getUserById، تصمم POST /users و GET /users/:id. يبدو هذا تمييزاً بسيطاً، لكنه يؤثر بعمق على كيفية توسع API، وكيف يتم توثيقه، وكيف يتعلم العملاء استخدامه.

نقطة نهاية REST مصممة جيداً لمستخدم تبدو كالتالي:

GET /users/42
Accept: application/json

Response 200:
{
  "id": 42,
  "name": "Ada Lovelace",
  "email": "ada@example.com",
  "role": "admin",
  "createdAt": "2025-11-14T09:00:00Z"
}

جمال REST هو بساطته. URL يحدد المورد، طريقة HTTP تحدد العملية، وجسم الاستجابة يحتوي على التمثيل. كل عميل HTTP في كل لغة يفهم هذا العقد بالفعل. التخزين المؤقت يعمل خارج الصندوق عبر رؤوس HTTP. أدوات مثل OpenAPI (المعروفة سابقاً بـ Swagger) تتيح لك توليد التوثيق، وSDKs العميل، ونماذج الخادم من ملف مخطط واحد.

REST يواجه مشاكل عندما يحتاج العملاء أشكالاً مختلفة من البيانات. عميل الجوال قد يحتاج فقط اسم المستخدم ودوره، بينما عميل لوحة المعلومات يحتاج الملف الشخصي الكامل مع بيانات المؤسسة المتداخلة. مع REST، إما تبني نقاط نهاية متعددة أو تجبر كل عميل على تنزيل التمثيل الكامل وتجاهل ما لا يحتاجه. هذه هي مشكلة الجلب الزائد، وكانت الدافع الأساسي لـ GraphQL.

GraphQL: دع العميل يصف بالضبط ما يحتاجه

GraphQL، الذي طورته Meta وأُطلق في 2015، يأخذ النهج المعاكس. بدلاً من أن يحدد الخادم استجابات ثابتة، يرسل العميل استعلاماً يصف بالضبط البيانات التي يريدها، ويعيد الخادم بالضبط ذلك الشكل. نقطة نهاية واحدة، أي شكل استجابة.

مخطط GraphQL يحدد الأنواع والعلاقات في مجالك. العميل يؤلف استعلامات ضد هذا المخطط، طالباً فقط الحقول التي يحتاجها. نفس مفهوم الموارد المتداخلة من REST يصبح حقولاً متداخلة في استعلام GraphQL، لكن العميل يتحكم في العمق والاختيار.

// GraphQL schema (SDL)
type User {
  id: ID!
  name: String!
  email: String!
  role: Role!
  posts: [Post!]!
}

type Post {
  id: ID!
  title: String!
  body: String!
}

enum Role { USER ADMIN MODERATOR }

type Query {
  user(id: ID!): User
}

عميل يحتاج فقط اسم المستخدم وعناوين منشوراته يرسل استعلاماً يطلب بالضبط تلك الحقول:

// Client query
query {
  user(id: 42) {
    name
    posts {
      title
    }
  }
}

// Response
{
  "data": {
    "user": {
      "name": "Ada Lovelace",
      "posts": [
        { "title": "Notes on the Analytical Engine" }
      ]
    }
  }
}

مبدأ التصميم الأساسي في GraphQL هو أن المخطط هو العقد. المخطط يحدد ما هو ممكن، والعميل يقرر ما يطلبه من الخيارات المتاحة. هذا يلغي الجلب الزائد، ويقلل عدد طلبات الشبكة (استعلام واحد يمكن أن يحل محل رحلات REST متعددة)، ويعطي فرق الواجهة الأمامية استقلالية عن تغييرات الخلفية لأن متطلبات العميل الجديدة لا تتطلب دائماً نقاط نهاية جديدة.

GraphQL يقدم تعقيداً خاصاً به. أداء الاستعلام أصعب في التنبؤ لأن العميل يتحكم في ما يُحمّل. مشكلة N+1 — حيث حل الحقول المتداخلة يؤدي إلى استعلام قاعدة بيانات مستقل لكل سجل أب — يتطلب حلول تجميع مثل DataLoader. التخزين المؤقت على مستوى HTTP لا يعمل لأن كل استعلام يضرب نفس نقطة نهاية POST، لذا استراتيجيات التخزين المؤقت على مستوى التطبيق ضرورية. ومنحنى التعلم للحلالين والتحولات والاشتراكات وأنواع الإدخال أكثر حدة من نموذج URL-وفعل REST المباشر.

GraphQL يعطي فرق الواجهة الأمامية استقلالية عن تغييرات الخلفية. لكن تلك الاستقلالية تأتي مع مسؤولية فهم خصائص أداء كل استعلام يرسله عميلك إلى الخادم.

gRPC: RPC عالي الأداء مبني على HTTP/2 وprotobuf

gRPC، الذي طورته Google في الأصل، يأخذ نهجاً آخر. بدلاً من الموارد والاستعلامات، يصمم gRPC واجهات API كاستدعاءات إجراء عن بعد — تعرف خدمة بالدوال، والعملاء يستدعون تلك الدوال كما لو كانت دوال محلية. الفرق التقني الرئيسي هو أن gRPC يستخدم المخازن المؤقتة للبروتوكول (protobuf) للتسلسل بدلاً من JSON، وHTTP/2 للنقل بدلاً من HTTP/1.1.

تعريف خدمة protobuf لا يشبه نقطة نهاية REST أو مخطط GraphQL:

syntax = "proto3";

service UserService {
  rpc GetUser (GetUserRequest) returns (User);
  rpc ListUsers (ListUsersRequest) returns (ListUsersResponse);
  rpc CreateUser (CreateUserRequest) returns (User);
  rpc StreamUserUpdates (StreamRequest) returns (stream UserUpdate);
}

message GetUserRequest {
  int32 id = 1;
}

message User {
  int32 id = 1;
  string name = 2;
  string email = 3;
  Role role = 4;
  string created_at = 5;
}

enum Role { ADMIN = 0; USER = 1; }

message StreamRequest {}

message UserUpdate {
  User user = 1;
  string event_type = 2;
}

Protobuf يسلسل إلى تنسيق ثنائي مضغوط أصغر بكثير من JSON وأسرع في التحليل. مقترناً بإرسال متعدد لـ HTTP/2 — تيارات متعددة عبر اتصال واحد — يحقق gRPC زمن وصول أقل بكثير وإنتاجية أعلى من REST أو GraphQL للاتصالات عالية الحجم. هذا يجعل gRPC الخيار المهيمن للاتصالات بين الميكروسيرفيسز، حيث كل ملي ثانية من عبء التسلسل وكل بايت على السلك مهم.

gRPC أيضاً يدعم أصلاً أربعة أنواع من التدفق: أحادي (طلب واحد، استجابة واحدة)، تدفق من الخادم (طلب واحد، تدفق استجابات)، تدفق من العميل (تدفق طلبات، استجابة واحدة)، وتدفق ثنائي الاتجاه (كلا الجانبين يتدفق في وقت واحد). هذا يجعله الخيار الأقوى لواجهات API في الوقت الفعلي بين البروتوكولات الثلاثة.

المقايضة هي أن gRPC أصعب في الاستخدام من المتصفحات. عملاء المتصفح لا يمكنهم الوصول إلى خدمات gRPC مباشرة لأنهم يفتقرون إلى التحكم الدقيق في إطارات HTTP/2. gRPC-Web موجود كحل بديل لكنه يضيف تعقيداً. رسائل Protobuf غير قابلة للقراءة البشرية أثناء النقل، مما يجعل التصحيح أصعب — تحتاج أدوات مثل grpcurl أو خدمة تأمل لتفقد حركة المرور. والنظام البيئي لتوثيق API أقل نضجاً من OpenAPI أو نظام التأمل في GraphQL.

كيف تقارن عبر الاهتمامات العملية

الاختيار بين REST وGraphQL وgRPC نادراً ما يكون قراراً تقنياً بحتاً. الاختيار الصحيح يعتمد على من هم عملاؤك، ونوع البيانات التي يحتاجونها، وقيود شبكتك وبنيتك التحتية. إليك كيف يقارن كل بروتوكول عبر الاهتمامات العملية الأكثر أهمية في الإنتاج.

إصدار API

REST يتعامل مع الإصدار من خلال URL أو رأس Accept. /v1/users و/v2/users يمكن أن يتعايشا إلى أجل غير مسمى، مما يسمح للعملاء بالترحيل بوتيرتهم الخاصة. هذا بسيط ومختبر في المعارك، لكنه يشجع على التكرار — نقطة نهاية v2 غالباً ما تكرر معظم منطق v1 مع بعض التغييرات. GraphQL يتجنب الإصدار تماماً بتطوير المخطط. الحقول المهملة مزينة بتوجيه @deprecated وتبقى في المخطط حتى يهاجر كل عميل. هذا يعمل جيداً عندما تتحكم في جميع العملاء لكنه يمكن أن يسبب احتكاكاً في واجهات API العامة حيث يتحديث العملاء ببطء. مخطط protobuf لـ gRPC متوافق مع المستقبل بطبيعته — يمكنك إضافة حقول دون كسر العملاء الحاليين، والحقول المهملة تزال بعد فترة ترحيل. هذه هي أنضف استراتيجية إصدار بين الثلاثة، لكنها تتطلب انضباطاً لعدم إعادة تسمية أو إزالة حقل أبداً دون دورة إهمال.

أنماط الترقيم

الترقيم في REST يتم عادةً بالترقيم القائم على المؤشر باستخدام حقل nextCursor، أو الترقيم القائم على الإزاحة مع معاملات page وlimit. مبدأ التصميم هو أن الاستجابة تحتوي على رابط أو رمز مميز تالي، والعميل يتبعه. الترقيم في GraphQL يستخدم مواصفات Relay Connection، التي تلف القوائم في حواف مع مؤشرات ومعلومات صفحة — أكثر إسهاباً لكن أكثر اتساقاً من نهج REST المخصص. الترقيم في gRPC يتم التعامل معه يدوياً في رسائل الطلب والاستجابة، عادةً مع حقل page_token وpage_size. لا يوجد معيار، لكن مخطط protobuf يجعل العقد صريحاً.

• REST: الترقيم القائم على المؤشر مع nextCursor في الاستجابة هو النمط الموصى به لواجهات API الإنتاجية
• GraphQL: مواصفات Relay Connection توفر نموذج ترقيم موحد مع hasNextPage وhasPreviousPage والمؤشرات
• gRPC: الترقيم يُعرف في رسائل proto الخاصة بك؛ النمط الشائع هو تضمين page_token وpage_size في الطلب وnext_page_token في الاستجابة

المصادقة والتفويض

البروتوكولات الثلاثة تعتمد على نفس أمان النقل الأساسي. REST عادةً يستخدم رموز Bearer في رأس Authorization. GraphQL يتبع نفس النمط — بما أن جميع الطلبات تذهب من خلال نقطة نهاية POST واحدة، يتم التحقق من الرمز المميز في طبقة GraphQL أو في برمجية وسيطة. gRPC يستخدم معترضات لإرفاق بيانات وصفية للمصادقة مع كل استدعاء، عادةً في شكل رموز JWT محمولة في رؤوس بيانات gRPC الوصفية. لا يصف أي من البروتوكولات الثلاثة طريقة مصادقة محددة — اختيار OAuth2 أو مفاتيح API أو المصادقة القائمة على الجلسة مستقل عن نمط API.

تحديد المعدل

تحديد المعدل أبسط مع REST لأن كل نقطة نهاية تمثل عملية محددة. تعد الطلبات لكل نقطة نهاية لكل عميل وتعيد 429 Too Many Requests عند تجاوز الحد. GraphQL يجعل تحديد المعدل أصعب لأن استعلاماً واحداً يمكن أن يؤدي كميات مختلفة بشكل كبير من العمل — استعلام لحقل واحد قد يكلف بحث قاعدة بيانات واحد، بينما استعلام بعلاقات متداخلة بعمق قد يكلف خمسين. واجهات API GraphQL عادةً تطبق تحديد المعدل القائم على التكلفة، حيث كل حقل له وزن ويتم حساب تكلفة الاستعلام الإجمالية قبل التنفيذ. تحديد المعدل في gRPC مشابه لـ REST لكنه يعمل على مستوى الدالة — تعد استدعاءات RPC لكل دالة لكل عميل، مع اعتبار إضافي أن استدعاءات التدفق تستهلك موارد لمدةها، وليس فقط بدايتها.

واجهات API في الوقت الفعلي والتدفق

REST يمكنه التعامل مع التحديثات في الوقت الفعلي من خلال WebSockets أو أحداث مرسلة من الخادم (SSE)، لكن أياً منهما ليس جزءاً من مواصفات REST — إنها بروتوكولات منفصلة ملحقة بجانب API HTTP. GraphQL لديه اشتراكات، وهي جزء أساسي من المواصفات. عميل يشترك في حدث ويتلقى تحديثات عبر اتصال WebSocket كلما حدث الحدث. gRPC لديه أقوى قصة للوقت الفعلي مع تدفقه الثنائي الاتجاه الأصلي عبر HTTP/2. استدعاء gRPC واحد يمكنه تدفق البيانات في كلا الاتجاهين في وقت واحد، وهو مثالي للوحات المعلومات في الوقت الفعلي، وتطبيقات الدردشة، والأنظمة القائمة على الأحداث. إذا كان الاتصال في الوقت الفعلي مطلباً أساسياً، تدفق gRPC هو الخيار الأكثر نضجاً وأداءً، تتبعه اشتراكات GraphQL، ثم REST مع WebSockets.

التوثيق وتجربة المطور

REST لديه أقوى نظام بيئي للتوثيق بفضل OpenAPI (المعروف سابقاً بـ Swagger). مواصفات OpenAPI تصف كل نقطة نهاية، ومعامل الطلب، ومخطط الاستجابة، وطريقة المصادقة في ملف YAML أو JSON قابل للقراءة آلياً. أدوات مثل Swagger UI تعرض هذا كصفحة توثيق تفاعلية، ومولدي الكود ينتجون SDKs لعشرات اللغات. نضج هذا النظام البيئي يعني أن مطوراً جديداً يمكنه الانتقال من قراءة مواصفات OpenAPI إلى إجراء أول استدعاء API ناجح في دقائق.

GraphQL لديه التأمل — نظام مدمج حيث تستعلم عن مخطط API من خلال نقطة نهاية خاصة. أدوات مثل GraphiQL وApollo Studio Explorer تتيح للمطورين تصفح المخطط، وكتابة الاستعلامات مع الإكمال التلقائي، ورؤية التوثيق مضمنًا. هذه تجربة رائعة للمطورين الذين يعرفون بالفعل أن API الخاص بك موجود، لكنها لا تساعد في قابلية اكتشاف محرك البحث أو أسواق API الخارجية بالطريقة التي تفعلها مواصفات OpenAPI.

gRPC يعتمد على ملفات proto كمصدر حقيقة. ملف proto هو كل من المخطط والتوثيق. أدوات مثل protoc-gen-doc تولد توثيقاً مرجعياً من ملفات proto، وتأمل gRPC يتيح للعملاء اكتشاف الخدمات ديناميكياً. تجربة المطور لـ gRPC تتحسن لكنها لا تزال متخلفة عن REST وGraphQL في نضج الأدوات، خاصة خارج نظام الميكروسيرفيسز.

متى تستخدم كل منها

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

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

gRPC هو الخيار الصحيح للاتصالات الداخلية بين الميكروسيرفيسز، وللأنظمة عالية الإنتاجية حيث يهم عبء التسلسل، ولتطبيقات التدفق في الوقت الفعلي. إذا كنت تبني نظاماً حيث كلا الطرفين تحت سيطرتك والأداء هو الاهتمام الأساسي، gRPC هو الخيار الأقوى.

لا شيء من هذه البروتوكولات متنافٍ. عمارة إنتاجية شائعة تستخدم gRPC للاتصالات بين الخدمات خلف جدار الحماية، وتكشف بوابة GraphQL تجمع البيانات من خدمات gRPC متعددة، وتوفر REST API للعملاء الخارجيين. السؤال ليس أي بروتوكول تستخدم في كل مكان — إنه أي بروتوكول تستخدم لكل واجهة في نظامك. فهم فلسفة التصميم وراء كل منها يعطيك الحكم لاتخاذ هذا الاختيار بشكل صحيح.