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

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

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

زر

للحصول على صورة أكبر حول محاكاة نقاط النهاية، راجع ما هي واجهة الـ Mock API. هنا نركز على الأداتين اللتين يلجأ إليهما المطورون أولاً.

ما هو json-server؟

json-server هي أداة مفتوحة المصدر لـ npm تحوّل ملف JSON عاديًا إلى واجهة REST API حقيقية. تكتب ملف db.json يصف مواردك، وتشغل أمرًا واحدًا، فتحصل على مسارات CRUD قياسية مدعومة بهذا الملف. طلبات الكتابة تعدّل الملف فعليًا، لذلك تبقى البيانات ثابتة بين الطلبات خلال جلستك.

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

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

قم بتثبيته من npm:

npm install json-server

أنشئ ملف db.json في مشروعك. مفاتيح المصفوفات (arrays) العلوية تصبح مسارات مجموعات (collection routes)؛ الكائنات (objects) العلوية تصبح مسارات لمورد واحد (single-resource routes):

{
  "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. هذا كل شيء؛ لديك الآن واجهة برمجة تطبيقات حية.

ملاحظة حول الإصدارات: أسقط json-server v1 علامة --watch القديمة، لذا فإن npx json-server db.json هو الأمر الحالي. إذا كنت تستخدم الإصدارات القديمة 0.x، فستظل ترى json-server --watch db.json في الدروس التعليمية.

المسارات التي تحصل عليها مجانًا

من ملف db.json أعلاه، يولد json-server سطح REST كاملاً.

لمصفوفة posts:

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

لكائن profile:

GET   /profile
PUT   /profile
PATCH /profile

الاستعلام مدمج أيضًا. يستخدم صيغة v1 نقطتين (:) للشروط:

GET /posts?views:gt=100       # views greater than 100
GET /posts?views:lte=50       # views less than or equal to 50
GET /posts?_sort=-views       # sort by views, descending
GET /posts?_page=1&_per_page=25   # pagination
GET /posts?_embed=comments    # include related comments

تتضمن العوامل المتاحة lt، lte، gt، gte، eq، ne، in، contains، startsWith، وendsWith. بالنسبة لملف بسيط وأمر واحد، هذا قدر كبير من واجهة برمجة التطبيقات.

JSONPlaceholder: واجهة برمجة تطبيقات وهمية بدون إعداد

أحيانًا لا ترغب حتى في تثبيت أداة. 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، ولكن هنا تكمن المشكلة: عمليات الكتابة وهمية. تعيد واجهة برمجة التطبيقات استجابة واقعية كما لو أن التغيير قد حدث، ولكن لا يتم حفظ أي شيء. قم بالتحديث وسيختفي منشورك "الجديد". هذا جيد لربط كود الواجهة الأمامية ببيانات يمكن التنبؤ بها؛ إنه ليس واجهة خلفية حقيقية.

json-server مقابل JSONPlaceholder

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

استخدم JSONPlaceholder عندما تحتاج إلى بيانات في هذه اللحظة ولا تهتم بماهيتها. استخدم json-server عندما تحتاج إلى مواردك الخاصة وعمليات كتابة ثابتة.

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

json-server و JSONPlaceholder ممتازتان في شيء واحد: تقديم JSON بسرعة. تبدأ فائدتهما في التراجع بمجرد أن ينمو المشروع ويتجاوز نموذجًا أوليًا فرديًا.

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

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

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

يعالج الـ Mock الذي يدرك المخطط (schema-aware mock) كل القيود المذكورة أعلاه. هذا هو المكان الذي تتولى فيه Apidog المهمة من json-server.

مدفوعة بالمخطط (schema-driven)، وليست مدفوعة بالملفات. حدد نقطة نهاية (أو استورد مواصفات OpenAPI الخاصة بك) وتقوم Apidog بمحاكاتها تلقائيًا. تظل المحاكاة والعقد متزامنين لأنهما نفس التعريف.
بيانات ذكية وديناميكية. يقرأ Apidog أسماء الحقول وأنواعها ويعيد قيمًا واقعية: بريد إلكتروني صالح لحقل email، وتاريخ لـcreatedAt، ورقم لـprice. يمكنك إرفاق قواعد بنمط Faker لكل حقل للتحكم الكامل. يتعمق دليلنا حول Faker.js في Apidog والمراجعة الأوسع لـ مولد بيانات الاختبار في إنتاج قيم واقعية.
عنوان URL سحابي قابل للمشاركة. تمنح Apidog الـ Mock عنوان URL مستضافًا يمكن لفريقك بالكامل وخط أنابيب CI الخاص بك استدعائه، وليس فقط localhost.
لا يتطلب Node. لا توجد حزمة لتثبيتها لكل مشروع ولا ملف db.json لرعايته.

محاكاة نفس واجهة برمجة التطبيقات في Apidog

قم بتنزيل Apidog وأنشئ أو افتح مشروعًا.
أضف نقطة نهاية، على سبيل المثال GET /posts، وحدد مخطط استجابتها (أو استورد ملف OpenAPI موجودًا).
ينشئ Apidog عنوان URL للـ Mock ويبدأ في إرجاع بيانات ذكية وواقعية لكل حقل على الفور.
هل تحتاج إلى قيم محددة؟ أضف قاعدة Mock لكل حقل لتثبيت الإخراج.
شارك عنوان URL للـ Mock مع فريقك أو أضفه إلى مجموعة الاختبار الخاصة بك و CI.

تحافظ على سرعة json-server في توفير "واجهة برمجة تطبيقات في دقائق"، وتكتسب التحقق، والبيانات الديناميكية، وعنوان URL يمكن للجميع الوصول إليه.

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

هل json-server مجاني؟ نعم، إنه مفتوح المصدر ومجاني الاستخدام. JSONPlaceholder مجاني أيضًا.

هل يحتفظ json-server بالبيانات؟ نعم. تكتب عمليات POST وPUT وPATCH وDELETE مرة أخرى إلى ملف db.json الخاص بك، لذا تبقى التغييرات قائمة بين الطلبات أثناء تشغيل الخادم. JSONPlaceholder يزيف عمليات الكتابة ولا يحفظ شيئًا.

هل يمكنني استخدام json-server في الإنتاج؟ لا. إنه مصمم للنماذج الأولية والاختبار. لا يحتوي على تحقق حقيقي، أو مصادقة، أو قابلية للتوسع.

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

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

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

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