Yusuf Khalidd

Posted on Jun 17 • Originally published at apidog.com

كيفية بناء REST API وهمي في دقائق (مع JSONPlaceholder)

أنت تبني واجهة أمامية، لكن الواجهة الخلفية ليست جاهزة. تحتاج إلى REST API تُرجع JSON واقعيًا الآن، مع عمليات GET وPOST وPUT وDELETE قابلة للاستخدام، حتى تواصل التطوير بدل انتظار الخادم الحقيقي.

جرّب Apidog اليوم

هذا هو دور json-server: تعطيه ملف JSON واحدًا فيحوّله إلى REST API خلال ثوانٍ، بدون كتابة كود خلفي. أما JSONPlaceholder فيوفر API وهمية مستضافة يمكنك استدعاؤها مباشرة بدون تثبيت أي شيء. في هذا الدليل ستتعلم متى تستخدم كل أداة، وكيف تبدأ بسرعة، ومتى تحتاج إلى mock أكثر ارتباطًا بالمخطط باستخدام Apidog.

للحصول على خلفية أوسع حول محاكاة نقاط النهاية، راجع ما هي واجهة الـ Mock API. هنا سنركز على الأداتين اللتين يبدأ بهما معظم المطورين: json-server وJSONPlaceholder.

ما هو json-server؟

json-server أداة مفتوحة المصدر من npm تحوّل ملف JSON عاديًا إلى REST API كاملة.

بدل أن تكتب خادم Express أو تضبط قاعدة بيانات، تنشئ ملفًا مثل db.json، ثم تشغل أمرًا واحدًا. بعدها تحصل على مسارات CRUD جاهزة:

GET    /posts
GET    /posts/:id
POST   /posts
PUT    /posts/:id
PATCH  /posts/:id
DELETE /posts/:id

طلبات الكتابة تعدّل ملف JSON نفسه، لذلك تبقى البيانات موجودة أثناء جلسة التطوير. هذا يجعله مناسبًا للنماذج الأولية، تطوير الواجهة الأمامية، العروض التوضيحية، والاختبارات المحلية. المشروع متاح على GitHub.

تثبيت وتشغيل json-server

ثبّت الحزمة من npm:

npm install json-server

أنشئ ملف db.json داخل مشروعك:

{
  "posts": [
    { "id": "1", "title": "First post", "views": 100 },
    { "id": "2", "title": "Second post", "views": 250 }
  ],
  "comments": [
    { "id": "1", "text": "Nice work", "postId": "1" }
  ],
  "profile": {
    "name": "apidog"
  }
}

شغّل الخادم:

npx json-server db.json

سيعمل افتراضيًا على:

http://localhost:3000

الآن يمكنك استدعاء نقاط النهاية مباشرة:

curl http://localhost:3000/posts

أو جلب عنصر واحد:

curl http://localhost:3000/posts/1

ملاحظة حول الإصدارات: في json-server v1 لم تعد تحتاج إلى --watch. الأمر الحالي هو npx json-server db.json. في الإصدارات القديمة 0.x قد ترى الأمر json-server --watch db.json في بعض الدروس.

كيف تتحول مفاتيح JSON إلى مسارات؟

في db.json:

المصفوفات العلوية تصبح collections.
الكائنات العلوية تصبح موارد فردية.

من المثال السابق، تحصل على:

GET    /posts
GET    /posts/:id
POST   /posts
PUT    /posts/:id
PATCH  /posts/:id
DELETE /posts/:id

وللكائن profile:

GET   /profile
PUT   /profile
PATCH /profile

مثال إنشاء منشور جديد:

curl -X POST http://localhost:3000/posts \
  -H "Content-Type: application/json" \
  -d '{
    "id": "3",
    "title": "Third post",
    "views": 10
  }'

مثال تحديث جزئي:

curl -X PATCH http://localhost:3000/posts/3 \
  -H "Content-Type: application/json" \
  -d '{ "views": 50 }'

مثال حذف:

curl -X DELETE http://localhost:3000/posts/3

استخدام الاستعلامات مع json-server

يدعم json-server الاستعلامات الجاهزة، مثل الفلترة والترتيب والصفحات.

في صيغة v1، تُستخدم النقطتان : للشروط:

GET /posts?views:gt=100
GET /posts?views:lte=50
GET /posts?_sort=-views
GET /posts?_page=1&_per_page=25
GET /posts?_embed=comments

أمثلة عملية:

# المنشورات التي عدد مشاهداتها أكبر من 100
curl "http://localhost:3000/posts?views:gt=100"

# ترتيب تنازلي حسب views
curl "http://localhost:3000/posts?_sort=-views"

# الصفحة الأولى، 25 عنصرًا لكل صفحة
curl "http://localhost:3000/posts?_page=1&_per_page=25"

العوامل المتاحة تشمل:

lt
lte
gt
gte
eq
ne
in
contains
startsWith
endsWith

هذا يكفي غالبًا لبناء واجهة أمامية كاملة قبل جاهزية الـ API الحقيقي.

JSONPlaceholder: API وهمية بدون إعداد

إذا كنت لا تريد تثبيت أي شيء، استخدم JSONPlaceholder. هي REST API وهمية مجانية مستضافة على jsonplaceholder.typicode.com.

مثال:

curl https://jsonplaceholder.typicode.com/posts/1

استجابة نموذجية:

{
  "userId": 1,
  "id": 1,
  "title": "sunt aut facere repellat provident",
  "body": "quia et suscipit..."
}

الموارد الجاهزة:

/posts — 100 عنصر
/comments — 500 عنصر
/albums — 100 عنصر
/photos — 5000 عنصر
/todos — 200 عنصر
/users — 10 عناصر

تدعم أيضًا:

POST
PUT
PATCH
DELETE

لكن انتبه: عمليات الكتابة لا تُحفظ فعليًا. ستحصل على استجابة تبدو واقعية، لكن البيانات لن تتغير على الخادم.

مثال:

curl -X POST https://jsonplaceholder.typicode.com/posts \
  -H "Content-Type: application/json" \
  -d '{
    "title": "New post",
    "body": "Demo body",
    "userId": 1
  }'

ستحصل على رد، لكن المنشور لن يبقى موجودًا إذا أعدت الطلب لاحقًا.

json-server مقابل JSONPlaceholder

	json-server	JSONPlaceholder
الإعداد	تثبيت npm + ملف `db.json`	بدون إعداد، فقط URL
مكان التشغيل	محليًا على جهازك	مستضاف وعام
بيانات مخصصة	نعم	لا، موارد ثابتة
استمرار عمليات الكتابة	نعم، داخل `db.json`	لا، عمليات وهمية
أفضل استخدام	نموذج أولي ببياناتك وشكلك	تجارب سريعة، تعليم، demos

استخدم JSONPlaceholder عندما تحتاج إلى بيانات فورًا ولا يهم شكلها كثيرًا.

استخدم json-server عندما تحتاج إلى:

أسماء موارد قريبة من API الحقيقي.
بيانات مخصصة.
عمليات POST/PUT/PATCH/DELETE تحفظ الحالة.
تجربة محلية سريعة للواجهة الأمامية.

مثال سريع: ربط React مع json-server

إذا كان json-server يعمل على:

http://localhost:3000

يمكنك جلب المنشورات في React هكذا:

import { useEffect, useState } from "react";

export default function Posts() {
  const [posts, setPosts] = useState([]);

  useEffect(() => {
    fetch("http://localhost:3000/posts")
      .then((res) => res.json())
      .then(setPosts);
  }, []);

  return (
    <ul>
      {posts.map((post) => (
        <li key={post.id}>
          {post.title} — {post.views} views
        </li>
      ))}
    </ul>
  );
}

وإضافة منشور:

async function createPost() {
  const res = await fetch("http://localhost:3000/posts", {
    method: "POST",
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      id: crypto.randomUUID(),
      title: "New post",
      views: 0
    })
  });

  const post = await res.json();
  console.log(post);
}

بهذا تستطيع بناء الواجهة قبل أن ينتهي فريق الخلفية من الـ API الحقيقي.

أين تتوقف فائدة هذه الأدوات؟

json-server وJSONPlaceholder ممتازتان لتقديم JSON بسرعة. لكنهما تصبحان محدودتين عندما يكبر المشروع.

أهم القيود:

لا يوجد validation حقيقي. إذا أرسلت نصًا في حقل يفترض أن يكون رقمًا، سيقبله json-server.
لا يوجد schema ملزم. البيانات الوهمية منفصلة عن عقد OpenAPI، لذلك قد تنحرف عن API الحقيقي.
لا توجد بيانات ديناميكية ذكية. الاستجابة تأتي من الملف فقط، ولا يتم توليد بريد إلكتروني أو تاريخ أو قيمة مختلفة تلقائيًا لكل طلب.
محلي ومستخدم واحد. json-server يعمل على localhost، لذلك لا يصل إليه الفريق أو CI بسهولة.
JSONPlaceholder لا يحفظ الحالة. لا يصلح لاختبار تدفقات تعتمد على بيانات مستمرة مثل سلة شراء أو خطوات تسجيل متعددة.

إذا تجاوزت مرحلة الملفات المسطحة، راجع أيضًا:

متى تنتقل إلى خادم Mock حقيقي؟

عندما تحتاج إلى mock مرتبط بالمخطط، وليس مجرد ملف JSON، يصبح من الأفضل استخدام أداة مثل Apidog.

الفكرة العملية:

تعرّف endpoint أو تستورد OpenAPI.
تحدد request/response schema.
تحصل على Mock URL مستضاف.
يبدأ الفريق باستخدامه قبل جاهزية backend.
تبقى الاستجابات مرتبطة بالعقد بدل ملف منفصل.

ما الذي يضيفه هذا مقارنة بـ json-server؟

Schema-driven بدل file-driven. التعريف نفسه يستخدم للتوثيق، الاختبار، والـ mock.
بيانات ذكية وديناميكية. يمكن توليد قيم واقعية حسب أسماء الحقول وأنواعها، مثل email وcreatedAt وprice.
قواعد Mock قابلة للتخصيص. يمكنك التحكم في القيم لكل حقل باستخدام قواعد شبيهة بـ Faker. راجع Faker.js في Apidog ومولد بيانات الاختبار.
Mock URL سحابي قابل للمشاركة. يمكن للفريق وCI استخدامه بدل localhost.
بدون Node لكل مشروع. لا تحتاج إلى تثبيت حزمة أو إدارة db.json في كل repo.

محاكاة نفس API في Apidog

لتطبيق نفس الفكرة بشكل عملي:

قم بتنزيل Apidog وأنشئ مشروعًا أو افتح مشروعًا موجودًا.
أضف endpoint مثل:

   GET /posts

عرّف مخطط الاستجابة، أو استورد ملف OpenAPI موجودًا.
استخدم Mock URL الذي ينشئه Apidog.
إذا احتجت قيمًا محددة، أضف قواعد Mock للحقول.
شارك Mock URL مع الفريق أو استخدمه داخل اختبارات CI.

بهذا تحتفظ بسرعة “API خلال دقائق” التي يوفرها json-server، لكن مع مخطط أوضح، بيانات ديناميكية، وURL يمكن للفريق كله استخدامه.

الأسئلة الشائعة

هل json-server مجاني؟

نعم. json-server مفتوح المصدر ومجاني. JSONPlaceholder مجاني أيضًا.

هل يحفظ json-server البيانات؟

نعم. عمليات POST وPUT وPATCH وDELETE تكتب التغييرات إلى ملف db.json. أما JSONPlaceholder فيحاكي عمليات الكتابة ولا يحفظها.

هل يمكن استخدام json-server في الإنتاج؟

لا. هو مخصص للنماذج الأولية والاختبارات المحلية. لا يوفر validation حقيقيًا، ولا مصادقة، ولا قابلية توسع مناسبة للإنتاج.

ما الفرق بين json-server وخادم Mock مثل Apidog؟

json-server يخدم ملف JSON كأنه API. أما Apidog فينشئ mocks من مخطط API، ويولّد بيانات واقعية، ويوفر Mock URL سحابيًا مشتركًا. للمزيد، راجع ما هي واجهة الـ Mock API وأدوات الـ Mocking لـ REST.

كيف أحصل على بيانات وهمية واقعية بدل صفوف ثابتة؟

استخدم مولد بيانات. يمكن لـ مولد بيانات الاختبار إنتاج سجلات متنوعة وواقعية، كما يمكن لـ Mock في Apidog توليد بيانات من مخططك.

النسخة المختصرة

استخدم json-server عندما تريد تحويل ملف JSON إلى REST API محلي بسرعة. استخدم JSONPlaceholder عندما تحتاج إلى API وهمية جاهزة بدون إعداد. وعندما تحتاج إلى schema، بيانات ديناميكية، mock قابل للمشاركة، وتوافق أقرب مع العقد الحقيقي، انتقل إلى خادم Mock مثل Apidog. يمكنك تنزيل Apidog، استيراد مواصفاتك، والبدء في استخدام mock مطابق للعقد من أول طلب.