ما هو الـ API؟ دليل المبتدئين لفهم وبناء واجهات برمجية

مقدمة

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

الكلمة المفتاحية الرئيسية: API
كلمات ثانوية: واجهات برمجية، تعلم البرمجة، REST، GraphQL، OAuth2.

وصف Meta مقترح (≤160 حرف)

فهم عملي للـ API: الأنواع الشائعة (REST/GraphQL/gRPC)، أساسيات التصميم، الأمان والتوثيق والمراقبة، مع أمثلة عملية لبناء واختبار واجهات برمجية.

لماذا يعتبر الـ API مهمًا اليوم؟

API كمنتج: نسبة كبيرة من الفرق تعتبر واجهاتها البرمجية مصدر دخل مباشر (نموذج API-as-a-Product).
استثمارات متزايدة: قرابة نصف المؤسسات تخطط لزيادة الاستثمار في واجهات البرمجة.
تحوّل نحو API‑First: فرق كثيرة تفضّل تصميم الـ API أولًا قبل الكود.
تسارع الذكاء الاصطناعي: قفزة ملحوظة في حركة الـ API المرتبطة بالـ AI خلال العام الماضي.

مراجع مختصرة: Postman – State of the API 2024، Treblle 2024، OWASP API Security 2023. (روابط في قسم المراجع)

ما هو الـ API بالضبط؟

Application Programming Interface هو اتفاق (Contract) يحدد كيف يتفاعل عميل (Client) مع خدمة (Server): ما هي النقاط الطرفية (Endpoints)، طرق HTTP (GET/POST/PUT/PATCH/DELETE)، المدخلات (Body/Query/Headers)، الاستجابات (JSON/XML)، وأكواد الحالة (Status Codes).

مفاهيم أساسية

Endpoint: عنوان يعرّف موردًا، مثل: /api/users/123.
Method: نوع العملية: قراءة (GET)، إنشاء (POST)، تحديث (PUT/PATCH)، حذف (DELETE).
Status Code: مثل 200، 201، 204، 400، 401/403، 404، 409، 422، 429، 500.
Headers: معلومات مرافقة (مثل Authorization, Content-Type).
Versioning: مثل /v1/… للحفاظ على التوافق عند التغييرات.

أنواع الـ API الشائعة

REST

يعتمد على الموارد (Resources) وHTTP.
مزايا: بساطة، توافق واسع، دعم HTTP Caching، أدوات كثيرة.
اعتبارات: تصميم الموارد بعناية، إدارة الأخطاء، النسخ (Versioning).

GraphQL

لغة استعلام تسمح للعميل بطلب ما يحتاجه بالضبط.
مزايا: حل مشكلات over/under‑fetching، مخطط موحّد، قدرات قوية للتجميع.
اعتبارات: التخبئة أعقد، إدارة الأمن على مستوى الحقول، مراقبة الأداء.

gRPC

بروتوكول عالي الأداء يعتمد Protobuf وHTTP/2.
مزايا: كفاءة في الاتصالات بين الخدمات (Service‑to‑Service)، توليد عميل/خادم تلقائيًا.
اعتبارات: ليس الأفضل للمتصفح مباشرة، يحتاج بوابة أو Proxy.

مثال عملي: REST API مبسّط

نموذج طلب/استجابة JSON

HTTP

GET /api/users/123 HTTP/1.1
Authorization: Bearer <token>
Accept: application/json

JSON

{
  "id": 123,
  "name": "Alaa",
  "email": "alaa@example.com"
}

إنشاء مورد

HTTP

POST /api/users HTTP/1.1
Content-Type: application/json
Authorization: Bearer <token>

JSON

{
  "name": "Alaa",
  "email": "alaa@example.com"
}

استجابة:

HTTP

HTTP/1.1 201 Created
Location: /api/users/124

مثال سريع على GraphQL

GRAPHQL

query GetUserAndPosts($id: ID!) {
  user(id: $id) {
    id
    name
    posts(limit: 3) {
      id
      title
    }
  }
}

طلب واحد يعيد حقولًا متعددة بدل عدة استدعاءات REST.

تصميم API جيد: مبادئ أساسية

تسمية الموارد

استخدم الأسماء الجمع: /users, /orders.
الموارد الفرعية: /users/{id}/orders.

الفلاتر والفرز والتقسيم (Pagination)

فلاتر عبر Query: GET /orders?status=paid&from=2025-01-01
ترتيب: sort=-createdAt
تقسيم صفحات: page=2&limit=20 أو cursor-based.

أخطاء ومعايير الاستجابة

هيكل ثابت للأخطاء:

JSON

{
  "error": {
    "code": "INVALID_INPUT",
    "message": "Email is invalid",
    "details": {"field": "email"}
  }
}

الإصدارات (Versioning)

مسار /v1/… أو عبر Header مخصص؛ وثّق سياسة الدعم وانتهاء الصلاحية (Deprecation).

أساسيات HTTP المتقدمة (Safety وIdempotency وConditional Requests)

الأمانة والسلامة (Safety)

العمليات الآمنة لا تغيّر حالة الخادم (GET, HEAD).
غير الآمنة تغيّر الحالة (POST, PUT, PATCH, DELETE).

خاصية Idempotency

PUT وDELETE يُفترض أنهما idempotent (نفس الطلب يتكرر دون تغيير إضافي).
POST ليس idempotent غالبًا؛ استخدم Idempotency-Key عند الحاجة لمنع الإنشاء المكرر.

التحديث الجزئي (PATCH)

استخدم JSON Merge Patch أو JSON Patch حسب الحاجة.

HTTP

PATCH /api/users/123
Content-Type: application/merge-patch+json

{"name":"Alaa Updated"}

الطلبات الشرطية والتخبئة المتقدمة

ETag + If-None-Match لعودة 304 Not Modified.
If-Match لحماية الكتابة المتنافسة (Optimistic Concurrency Control).

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

مفاتيح API (API Keys)

بسيطة، مناسبة للخدمات الداخلية/القراءة العامة؛ قيد النطاق والمصدر وحدود المعدّل.

OAuth 2.0 / OpenID Connect

تطبيقات خارجية تحتاج وصولًا إلى بيانات المستخدم بلا مشاركة كلمة المرور.
التدفقات الشائعة: Authorization Code (ويب)، Client Credentials (سيرفر‑إلى‑سيرفر).

JWT (JSON Web Token)

رمز موقّع يحمل Claims؛ راقب الحجم والانتهاء والتدوير.

الأمان: ما ينبغي الانتباه له

اطلع على OWASP API Security Top 10 (2023): BOLA/IDOR, Broken Authentication, Injection, Excessive Data Exposure…
طبّق TLS دائمًا، وحدود المعدّل، واكتشاف الشذوذ، وسجّل محاولات الدخول.
تحقق من صلاحيات الحقول في GraphQL (Field‑Level Authorization) واتبّع مبدأ Least Privilege.
CORS مضبوط: لا تفتح * على Authorization؛ عرّف origins صريحة.

مثال CORS آمن في Express

JAVASCRIPT

app.use(cors({
  origin: ["https://app.example.com"],
  methods: ["GET","POST","PUT","PATCH","DELETE"],
  allowedHeaders: ["Content-Type","Authorization"],
  credentials: true
}));

منع الوصول الأفقي (BOLA/IDOR)

JAVASCRIPT

// تأكد من أن المستخدم يملك المورد قبل الإرجاع
const order = await db.orders.findById(orderId);
if (order.userId !== auth.user.id) return res.status(403).json({ error: { code: 'FORBIDDEN' }});

دورة حياة الـ API (API Lifecycle)

1) التصميم أولًا (API‑First)

صِف واجهتك عبر OpenAPI (Swagger)؛ شارك المخطط مبكرًا مع المستهلكين، ووفّر Mock Server.

2) التطوير والاختبارات

اختبارات وحدات وتكامل، Contract Testing مع المستهلكين، وسيناريوهات Happy/Edge paths.
أدوات: Postman/Newman، Jest/Supertest، Pact.

3) التوثيق والتجربة

وثّق الأمثلة وقابلية التجربة (Try it) عبر Swagger UI أو بوابة مطوّرين (Developer Portal).

4) الإطلاق والمراقبة

CI/CD للنشر الآمن، مراقبة زمن الاستجابة/الأخطاء، وتتبع الإصدارات.
جمع الميتريكس (Latency, Error Rate, Throughput) وTracing عبر OpenTelemetry.

مثال تطبيقي: OpenAPI 3.1 (مقتطف)

YAML

openapi: 3.1.0
info:
  title: Todo API
  version: 1.0.0
servers:
  - url: https://api.example.com
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
paths:
  /todos:
    get:
      security:
        - bearerAuth: []
      responses:
        "200":
          description: List todos
    post:
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TodoCreate'
      responses:
        "201": { description: Created }

مثال تطبيقي: بناء API صغير بـ Node.js + Express

تهيئة مشروع سريع

BASH

mkdir todo-api && cd todo-api
npm init -y
npm i express zod cors
npm i -D nodemon

كود خادم مبسّط

JAVASCRIPT

// index.js
import express from 'express';
import cors from 'cors';
import { z } from 'zod';

const app = express();
app.use(cors());
app.use(express.json());

const Todo = z.object({
  title: z.string().min(1),
  done: z.boolean().default(false)
});

let todos = [];
let idSeq = 1;

app.get('/api/todos', (req, res) => {
  res.json(todos);
});

app.post('/api/todos', (req, res) => {
  const parse = Todo.safeParse(req.body);
  if (!parse.success) {
    return res.status(400).json({ error: { code: 'INVALID_INPUT', details: parse.error.errors }});
  }
  const todo = { id: idSeq++, ...parse.data };
  todos.push(todo);
  res.status(201).json(todo);
});

app.patch('/api/todos/:id', (req, res) => {
  const id = Number(req.params.id);
  const idx = todos.findIndex(t => t.id === id);
  if (idx === -1) return res.status(404).json({ error: { code: 'NOT_FOUND' }});
  const merged = { ...todos[idx], ...req.body };
  const parse = Todo.partial().safeParse(merged);
  if (!parse.success) return res.status(400).json({ error: { code: 'INVALID_INPUT', details: parse.error.errors }});
  todos[idx] = parse.data;
  res.json(todos[idx]);
});

app.delete('/api/todos/:id', (req, res) => {
  const id = Number(req.params.id);
  const len = todos.length;
  todos = todos.filter(t => t.id !== id);
  if (todos.length === len) return res.status(404).json({ error: { code: 'NOT_FOUND' }});
  res.status(204).end();
});

app.listen(3000, () => console.log('API running on http://localhost:3000'));

اختبار سريع عبر curl

BASH

curl -s -X POST http://localhost:3000/api/todos \
  -H 'Content-Type: application/json' \
  -d '{"title":"تعلم API"}'

curl -s http://localhost:3000/api/todos

GraphQL بعمق: الأداء والأمان

مشكلة N+1 والحل عبر DataLoader

اجمع الاستعلامات المتكررة في دفعات لتقليل الوصول للقاعدة.

تفويض على مستوى الحقول

استخدم Directives (مثل @auth) لتقييد حقول حساسة.

تقدير التعقيد (Query Cost)

ضع حدودًا للتعقيد والعمق لتفادي إساءة الاستخدام.

gRPC بعمق: متى ولماذا؟

نموذج proto بسيط

PROTO

syntax = "proto3";
package todo;
service TodoService {
  rpc List (ListRequest) returns (ListResponse);
}
message ListRequest { int32 limit = 1; }
message Todo { int32 id = 1; string title = 2; bool done = 3; }
message ListResponse { repeated Todo items = 1; }

مثالي لاتصالات الخوادم عالية الأداء وStreaming.

البنية: API Gateway وBFF

API Gateway: مصادقة مركزية، سياسات Rate limiting، تحويل الاستجابات، التحقق من المخططات عند الحافة.
BFF (Backends for Frontends): واجهات مخصصة لكل عميل (ويب/موبايل) لتقليل الشد والجذب بين الفرق.

المراقبة والقياس (Observability)

SLIs/SLOs

حدد أهدافًا مثل: زمن الاستجابة P95 < 300ms، معدل الخطأ < 0.5%.

التتبّع الموزّع (Tracing)

استخدم W3C Trace Context (traceparent) لربط الطلبات بين الخدمات.

ربط السجلات (Log Correlation)

أضف Correlation-ID في كل طلب لتسهيل التحقيق في الأعطال.

الاختبارات: من الوحدة إلى العقد (Contract Testing)

مثال بسيط مع Newman (Postman CLI)

BASH

newman run api-collection.json --env-var baseUrl=https://api.example.com

Contract Testing بفكرة Pact (تصوري)

يعرّف المستهلك توقعات دقيقة، ويتحقق المزود من مطابقة العقد قبل النشر.

سياسة التوافق والتغييرات الآمنة

تغييرات متوافقة خلفيًا (Backwards-Compatible)

إضافة حقول اختيارية، إضافة Endpoints جديدة، توسيع قيم Enum.

تغييرات كاسرة (Breaking)

إزالة/إعادة تسمية حقول، تغيير أنواع الحقول؛ يتطلّب نسخة جديدة + سياسة Deprecation واضحة وSunset Header.

تحسين الأداء والمقاييس

التخبئة (Caching)

REST: استخدم ETag, Cache-Control, If-None-Match.
GraphQL: طبقات تخبئة على مستوى الحقل/الاستعلام، أو DataLoader لتقليل N+1.

حدود المعدّل (Rate Limiting) والموازنة (Throttling)

احمِ واجهتك من الإساءة، واضبط سياسات لكل مفتاح/عميل، وأرسل رؤوسًا مثل X-RateLimit-Remaining ووقت إعادة الضبط.

الاستقرار تحت الضغط

Circuit Breaker، Retry مع Exponential Backoff، وBulkhead لتقسيم الموارد.

شيفرة وأدوات تساعدك على الانطلاق

OpenAPI لتوليد العملاء/الخوادم.
Postman/Insomnia للاختبار التفاعلي.
Prism أو Mock Service Worker للتجربة دون خادم جاهز.
k6/Locust لاختبارات الضغط.
OpenTelemetry للمقاييس والتتبّع.

أخطاء شائعة وكيف تتفاداها

وضع منطق العمل في Controllers معقّدة بدل طبقات منفصلة (Service/Repository).
تجاهل Pagination ما يسبب استجابات ضخمة.
تسرّب المفاتيح/الرموز في الـ Logs.
عدم توحيد شكل الأخطاء، ما يربك المستهلكين.
الإصرار على REST فقط أو GraphQL فقط؛ اختر الأداة المناسبة للحالة.

متى أستخدم REST أو GraphQL أو gRPC؟

REST: CRUD بسيط، دعم تخبئة HTTP، سهولة التكامل العام.
GraphQL: واجهة واحدة لتجميع خدمات متعددة، واجهات مرنة لتطبيقات متعددة الواجهات.
gRPC: اتصالات كثيفة بين الخدمات، زمن استجابة منخفض، وStreaming ثنائي الاتجاه.

أي بروتوكول أختار؟ جدول قرار

اختيار البروتوكول المناسب يعتمد على طبيعة البيانات، عدد المستهلكين، وقيود الشبكة. الجدول التالي يلخّص القرار:

الحالة	REST	GraphQL	gRPC
CRUD بسيط + تخبئة HTTP	ممتاز	جيد	غير ملائم للمتصفح
تجميع بيانات من خدمات متعددة	مقبول	ممتاز	جيد داخليًا
زمن استجابة منخفض بين خدمات	جيد	مقبول	ممتاز
دعم واسع للأدوات العامة	ممتاز	ممتاز	جيد
بث ثنائي الاتجاه/Streaming	محدود	محدود	ممتاز

خلاصة: واجهات عامة للمستخدم النهائي تميل إلى REST/GraphQL؛ اتصالات داخلية كثيفة الأداء تميل إلى gRPC.

بلايبوك الأمان السريع (عملي)

قبل الإطلاق

TLS إلزامي؛ لا تقبل HTTP عارٍ.
سياسات Rate Limiting لكل مفتاح/مستخدم مع رسائل خطأ واضحة وRetry-After.
تحقّق صلاحيات الموارد (تفادي BOLA/IDOR).
إخفاء تفاصيل الأخطاء في الإنتاج (منع تسريب معلومات حساسة).
تمكين سجلات مدقّقة (Audit Logs) لكل عمليات الإنشاء/التعديل/الحذف.

بعد الإطلاق (الأسبوع 1–2)

مراقبة P95 latency, خطأ 5xx, ومعدل الفشل < 0.5%.
اختبارات اختراق أساسية (OWASP API Top 10) وإغلاق الثغرات السريعة.
تدوير المفاتيح السرّية إن لزم (Key Rotation) وتفعيل تنبيهات الاستخدام الشاذ.

دوريًا (أسبوعي/شهري)

مراجعة صلاحيات الأدوار (Least Privilege) وتقارير الوصول غير المعتاد.
اختبار استرجاع الكوارث (DR) وخطط النسخ الاحتياطي.

كود HMAC للتحقق من Webhook (Node.js)

JAVASCRIPT

import crypto from 'node:crypto';
export function verifyWebhook(rawBody, signatureHex, secret) {
  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  try {
    return crypto.timingSafeEqual(Buffer.from(signatureHex, 'hex'), Buffer.from(expected, 'hex'));
  } catch {
    return false;
  }
}

استخدام مع Express (body raw)

JAVASCRIPT

import express from 'express';
const app = express();
app.post('/api/webhooks/payments', express.raw({ type: 'application/json' }), (req, res) => {
  const sig = req.get('x-signature');
  if (!verifyWebhook(req.body, sig, process.env.WH_SECRET)) return res.status(400).end();
  // عالج الحدث ثم أعد استجابة سريعة
  res.status(204).end();
});

طلبات Idempotency لمنع التكرار

CODE

POST /api/orders
Idempotency-Key: 7f9e0c5a-2f1d-4f5e-b1e6-9f2b6c3d1a45
Content-Type: application/json

خزّن نتيجة المفتاح لمدة قصيرة (مثلاً 24 ساعة) وأعد نفس الاستجابة عند التكرار.

مختبر أداء k6 (HTTP)

سكربت اختبار أساسي

JAVASCRIPT

import http from 'k6/http';
import { sleep, check } from 'k6';
export const options = {
  vus: 20,
  duration: '1m',
  thresholds: {
    http_req_duration: ['p(95)<300'],
    http_req_failed: ['rate<0.005']
  }
};
export default function () {
  const res = http.get('https://api.example.com/todos');
  check(res, { 'status 200': r => r.status === 200 });
  sleep(1);
}

قراءة النتائج واتخاذ إجراء

إذا تجاوز P95 حدّك المستهدف: طبّق caching، قلّل استعلامات قاعدة البيانات (N+1)، أو استخدم تجميع/توازي.
إذا زاد http_req_failed: راجع سياسات timeouts/retries والدوائر الواقية (Circuit Breaker).

Checklist إطلاق (قبل/أثناء/بعد)

قبل الإطلاق

OpenAPI محدّث ومجرّب + أمثلة موثّقة.
سياسات Rate Limit + Retry-After + رسائل خطأ متناسقة.
مصادقة/تفويض واضحان (OAuth2/JWT) مع انتهاء صلاحية وتدوير مفاتيح.
مراقبة: لوحات Latency/Error/Throughput وتنبيهات 5xx.
خطة Deprecation/Versioning واضحة.

أثناء الإطلاق

تدرّج المرور (Canary/Blue-Green) + فحوص صحّة آلية.
مراقبة حيّة لكل Endpoint ذي خطورة عالية.

بعد الإطلاق

مراجعة سجلات الأخطاء خلال أول 24–72 ساعة.
مقابلة سريعة مع المستهلكين الأوائل لجمع تغذية راجعة.
خطة تحسين ربع سنوية (أداء/أمان/توثيق).

أسئلة مقابلات تقنية عن API (مختصرة)

ما الفرق بين المصادقة (Authentication) والتفويض (Authorization)؟

المصادقة: من أنت؟ التفويض: ماذا يسمح لك أن تفعل؟ غالبًا OAuth2/OIDC للمصادقة وScopes/Policies للتفويض.

ما معنى Idempotency؟ ومتى أستخدمه؟

تكرار نفس الطلب يعطي نفس الأثر (PUT/DELETE متوقَّعان كذلك). استخدم Idempotency-Key مع POST للمدفوعات والطلبات الحساسة.

متى أستخدم 422 بدل 400؟

400 Bad Request لهيكل طلب غير صحيح؛ 422 Unprocessable Entity عندما الهيكل صحيح لكن القيم غير صالحة حسب قواعد المجال.

Pagination مفضّل؟

Cursor‑based أكثر ثباتًا وأداءً في البيانات المتغيرة؛ Offset‑based أبسط لكنه هشّ مع إدراجات/حذف متزامن.

كيف أتجنب BOLA/IDOR؟

تحقق ملكية المورد لكل طلب بناءً على هوية المستخدم وسياق التفويض، ولا تعتمد على معرفات قابلة للتخمين.

ما فرق 401 و403؟

401 يعني غير مصادق؛ 403 يعني مصادق لكن غير مخوّل للوصول.

كيف أوثّق API جيدًا؟

OpenAPI شامل + أمثلة واقعية + "Try it" + سياسة إصدارات واضحة + changelog وترحيل.

متى أختار REST أو GraphQL؟

REST لواجهات عامة وHTTP caching؛ GraphQL عندما تحتاج تجميع بيانات مرن لمختلف الواجهات (ويب/موبايل) وتريد تقليل الاستدعاءات.

خاتمة

الـ API ليس مجرد طبقة تقنية، بل منتج يحتاج تصميمًا واعيًا، وأمنًا صارمًا، وتوثيقًا وتجربة مطوّرين ممتازة. بالتزامك بالمبادئ المذكورة، ستبني واجهات قابلة للتوسّع، آمنة، وقابلة للصيانة تخدم منتجك ومستخدميك لسنوات.

دعوة إلى الإجراء: اختر حالة استخدام واحدة من مشروعك، وابدأ بتوصيفها عبر OpenAPI، ثم جرّب نموذجًا أوليًا (Mock) وشارك مع فريقك. بعد ذلك، أضف المصادقة والاختبارات وراقب المقاييس. ستتعلم الكثير من أول دورة كاملة.

المراجع

Postman – State of the API 2024: 74% API‑First، 48% زيادة الاستثمار
https://www.postman.com/state-of-api/2024/
Postman – تقرير PDF (2024): 62% APIs تدرّ دخلًا
https://voyager.postman.com/doc/postman-state-of-the-api-report-2024.pdf
Postman – AI & APIs: زيادة 73% في حركة واجهات الذكاء الاصطناعي
https://www.postman.com/state-of-api/2024/artificial-intelligence/
Treblle – Anatomy of an API 2024: متوسط ~42 endpoint ونمو كبير في AI APIs
https://report.treblle.com/
OWASP API Security Top 10 – 2023
https://owasp.org/API-Security/editions/2023/en/0x11-t10/
مقارنة REST/GraphQL ونقاط التخبئة
https://tailcall.run/graphql/graphql-vs-rest-api-comparison/
State of GraphQL Federation 2024
https://wundergraph.com/state-of-graphql-federation/2024