Next.js/api routes

تٌعد مسارات الواجهة البرمجية API طريقة لبناء الواجهة البرمجية الخلفية لتطبيقك باستخدام Next.js الذي يعمل في هذه الحالة كواجهة أمامية frontend وواجهة خلفية backend. إذ يُربط كل ملف ضمن المجلد pages/api بالمسار */api/ ويُعامل كوصلة API (نقطة اتصال مع الواجهة البرمجية) بدلًا من كونه صفحة page. تمثّل هذه الوصلات تجمّعات bundles في جانب الخادم فقط ولن تزيد حجم تجميعة التطبيق من جانب العميل. يعيد مسار API التالي pages/api/user.js على سبيل المثال استجابة بصيغة json مع رمز الحالة 200:

export default function handler(req, res) {
  res.status(200).json({ name: 'John Doe' })
}

ملاحظة: مسارات API ستتأثر عبر ضبط pageExtensions في الملف next.config.js.

ولكي يعمل مسار API لا بدّ من تصدير دالة على أنها افتراضية default (مثل الدالة handler في المثال السابق) ومن ثم تستقبل المعاملات التالية:

• req: يضم نسخة عن الكائن http.IncomingMessage بالإضافة إلى بعض الأدوات الوسطية middlewares المبنية مسبقًا (سنتعرف عليها لاحقًا في هذه الصفحة).
• res: يضم نسخة عن الكائن http.ServerResponse بالإضافة إلى دوال مساعدة (سنتعرف عليها لاحقًا في هذه الصفحة).

يمكنك استخدام الكائن req.method ضمن معالج الطلب request handler إن أردت التعامل مع الأنواع المختلفة لطلبات HTTP في مسار API. إليك مثالًا:

export default function handler(req, res) {
  if (req.method === 'POST') {
    // POST يعالج طلب من النوع 
  } else {
    // يعالج بقية أنواع الطلبات
  }
}

حالات استخدام مسارت API في Next.js

يمكنك بناء الواجهة البرمجية الخلفية API بأكملها لمشروعك الجديد باستخدام مسارات API. فإن كان لديك واجهة برمجية جاهزة، لا حاجة عندها لتوجيه الاستدعاءات إليها من خلال مسارات API. إليك بعض الحالات التي يمكن استخدام مسارات API فيها:

• إخفاء عنوان URL عن خدمة خارجية (مثال: api/secret/ بدلًا عن https://company.com/secret-url)
• استخدام متغيرات بيئة ضمن الخادم للولوج الآمن إلى خدمات خارجية.

محاذير

• لا تحدد مسارات API ترويسات مشاركة الموارد ذات الأصل المختلط CORS، أي أنها افتراضيًا للموارد ذات الأصل المشترك same-origin فقط. يمكنك التحكم بهذا السلوك عبر تغليف معالج الطلب باستخدام أداة CORS وسطية.
• لا يمكن استخدام مسارات API مع next export.

مسارات API ديناميكية

تدعم مسارات API الوجهات الديناميكية dynamic routes وتخضع لجميع قواعد تسمية الملفات التي تستخدم مع الصفحات pages. فشيفرة مسار API للوجهة pages/api/post/[pid].js هي كالتالي:

export default function handler(req, res) {
  const { pid } = req.query
  res.end(`Post: ${pid}`)
}

فإن أرسل طلب إلى api/post/abc/ فسيكون الرد نصًا هو Post: abc.

الصفحة index ومسارات API الديناميكية

تهيئ المسارات بما يتطابق مع معايير REST (أو كما يُعرف RESTful) بالشكل التالي الأكثر شيوعًا:

• GET api/posts: يُحضر قائمة بالمنشورات التي قد تكون مرتبة في صفحات.
• GET api/posts/12345: يُحضر المنشور ذو المعرّف 12345.

يمكن نمذجة هذه الأمثلة كما يلي:

• الخيار الأول:
  • api/posts.js/
  • api/posts/[postId].js/
• الخيار الثاني:
  • api/posts/index.js/
  • api/posts/[postId].js/

إنّ النموذجين السابقين متكافئين. وهنالك خيار ثالث يستخدم فقط النموذج api/posts/[postId].js/ لكنه لا يصلح لأنّ المسارات الديناميكية (بما فيها التقاط جميع المسارات Catch-all routes) لا تمتلك حالة غير محددة undefined وبالتالي لن يتمكن GET api/posts من مطابقة الوجهة api/posts/[postId].js/ أبدًا.

التقاط جميع الوجهات من خلال مسار API الديناميكي

بالإمكان توسعة مسارات API الديناميكية لمطابقة كل المسارات وذلك بإضافة ثلاث نقاط ... داخل القوسين المربعين. إليك مثالًا:

• تطابق الوجهة pages/api/post/[...slug].js المسار api/post/a/ كما تطابق api/post/a/b/ و api/post/a/b/c/ وهكذا. بإمكانك طبعًا اختيار أي اسم بدلًا من slug مثل [param...].

تُرسل معاملات البحث كمعاملات استعلام (slug مثال على ذلك) إلى الصفحة، وتشكل المعاملات دائمًا مصفوفة. وبالتالي سيكون كائن الاستعلام عن المسار api/post/a/ مثلًا هو:

{ "slug": ["a"] }

في حالة api/post/a/b/ وأية مسارات مطابقة أخرى، ستُضاف المعاملات الجديدة إلى المصفوفة كالتالي:

{ "slug": ["a", "b"] }

يبدو مسار API إلى الوجهة pages/api/post/[...slug].js كالتالي:

export default function handler(req, res) {
  const { slug } = req.query
  res.end(`Post: ${slug.join(', ')}`)
}

وهكذا سيكون النص Post: a, b, c هو الرد على الطلب api/post/a/b/c/.

التقاط جميع الوجهات اختياريًا

يمكن التقاط جميع الوجهات اختياريًا بإضافة المعامل بين قوسين مربعين مزدوجين مثل [[...slug]] إذ ستطابق الوجهة pages/api/post/[[...slug]].js مثلًا المسارات api/post/ و api/post/a/ و api/post/a/b/ وهكذا.

إنّ الاختلاف الرئيسي بين التقاط جميع الوجهات والتقاط جميع الوجهات اختياريًا هو أنّ الالتقاط الاختياري سيطابق أيضًا المسارات التي لا تضم معامل البحث (المسار api/post/ مثالًا).

سيكون كائن الاستعلام query التالي:

{ } //`/api/post` سيحصل على المسار 
{ "slug": ["a"] } //(مصفوفة وحيد العنصر) `/api/post/a` سيحصل على المسار 
{ "slug": ["a", "b"] } //(مصفوفة متعددة العناصر) `/api/post/a/b` سيحصل على

محاذير

• لوجهات API المحددة مسبقًا الأفضلية على الوجهات الدينياميكية والتي لها الأفضلية على جميع المسارات الملتقطة. إليك بعض الأمثلة:
  • pages/api/post/create.js يتطابق مع api/post/create/.
  • pages/api/post/[pid].js يتطابق مع api/post/1/ و api/post/abc/ وليس مع api/post/create/.
  • pages/api/post/[...slug].js يتطابق مع api/post/1/2/ و /api/post/a/b/c/ وليس مع api/post/create/ و api/post/abc/.

مساعدو الطلب Request Helpers

تزوّدك مسارات API بمساعدي الطلب request helpers يحللون الطلب الوارد (req) وهي:

• req.cookies: وهي كائن يتضمن ملفات تعريف الارتباط التي يرسلها الطلب. قيمته الافتراضية {}.
• req.query: وهي كائن يتضمن الاستعلام query، وقيمته الافتراضية {}.
• req.body: وهي كائن يضم جسم الطلب يحلل وفقًا للخاصية content-type أو يأخذ القيمة null إن لم يُرسل جسم الطلب.

إعدادات مخصصة

يمكن لمسار API أن يُصدّر كائن التهيئة config ليغيّر التهيئة الافتراضية وهي:

export const config = {
  api: {
    bodyParser: {
      sizeLimit: '1mb',
    },
  },
}

يضم الكائن api كل الإعدادات المتاحة لمسار API، ويُفعَّل الخيار bodyParser (تحليل جسم الطلب) تلقائيًا. لكن بإمكانك تعطيله بضبط قيمته على false وذلك إن أردت استهلاك جسم الطلب عبر خيار النقل المستمر لبياناته Stream أو بواسطة الخيار raw-body. إحدى الحالات التي يُعطَّل فيها الخيار bodyParsing هي الحالة التي نريد فيها التحقق من القيمة الخام لجسم طلب خطاف ويب webhook مصدره GitHub مثلًا:

export const config = {
  api: {
    bodyParser: false,
  },
}

تعطي القيمة bodyParser.sizeLimit الحجم الأقصى المسموح للجسم المُحلل بأية صيغة تدعمها المكتبة bytes كالتالي:

export const config = {
  api: {
    bodyParser: {
      sizeLimit: '500kb',
    },
  },
}

تخبر الراية externalResolver الخادم إن كان المسار سيُعالج من قبل محلل خارجي مثل express أو connect. بتفعيل هذه الراية سيوقف التنبيهات التي سببتها الطلبات غير المحللة unresolved:

export const config = {
  api: {
    externalResolver: true,
  },
}

يُفعّل الخيار responseLimit تلقائيًا ويعطي تنبيهًا عندما يزيد حجم جسم الطلب عن 4 ميغابايت. فإن لم تكن تستخدم Next.js في بيئة دون خادم، وكنت تدرك جيدًا تبعات الأداء عند عدم وجود شبكة توزيع محتوى أو مضيف خاص بالوسائط، بإمكانك ألا تحدد قيمة لهذا الخيار بضبطها على false.

export const config = {
  api: {
    responseLimit: false,
  },
}

يمكن أن تأخذ responseLimit قيمة تمثل عدد البايتات أو أية قيمة نصية تدعمها المكتبة مثل 1000 أو '500kb' أو '3mb'. تمثّل هذه القيمة أعلى حجم للاستجابة قبل عرض تنبيه تجاوز الحجم المحدد (القيمة الافتراضية هي 4 ميغابايت):

export const config = {
  api: {
    responseLimit: '8mb',
  },
}

توسعة الكائنين req و res باستخدام TypeScript

نظرًا لبعض التبعات الأمنية الخاصة بالأنواع، لا يُنصح بتوسعة الكائنين req و res بل استخدم دوال للعمل معهما:

// utils/cookies.ts

import { serialize, CookieSerializeOptions } from 'cookie'
import { NextApiResponse } from 'next'

/**
 *res ضبط ملفات تعريف الاراتباط باستخدام الكائن 
 */

export const setCookie = (
  res: NextApiResponse,
  name: string,
  value: unknown,
  options: CookieSerializeOptions = {}
) => {
  const stringValue =
    typeof value === 'object' ? 'j:' + JSON.stringify(value) : String(value)

  if ('maxAge' in options) {
    options.expires = new Date(Date.now() + options.maxAge)
    options.maxAge /= 1000
  }

  res.setHeader('Set-Cookie', serialize(name, stringValue, options))
}

// pages/api/cookies.ts

import { NextApiRequest, NextApiResponse } from 'next'
import { setCookie } from '../../utils/cookies'

const handler = (req: NextApiRequest, res: NextApiResponse) => {
    //الذي سيضيف الترويسة res استدعاء الدالة الصرفة باستخدام الكائن
    //`set-cookie` header
  setCookie(res, 'Next.js', 'api-middleware!')
    //لنتمكن من عرضها في المتصفح set-cookie إعادة الترويسة 
   
  res.end(res.getHeader('Set-Cookie'))
}

export default handler

إن لم تجد بدًا من توسعة هذين الكائنين، عليك أن تنشئ نوعًا خاصًا بك ليضم الخصائص الإضافية:

// pages/api/foo.ts

import { NextApiRequest, NextApiResponse } from 'next'
import { withFoo } from 'external-lib-foo'

type NextApiRequestWithFoo = NextApiRequest & {
  foo: (bar: string) => void
}

const handler = (req: NextApiRequestWithFoo, res: NextApiResponse) => {
  req.foo('bar') //دون أخطاء في النوع req.foo يمكن استخدام الخاصية 
  res.end('ok')
}

export default withFoo(handler)

تذكر أن هذا الأسلوب ليس آمنًا لأن الشيفرة ستُصرَّف حتى لو لم تُصدِّر الدالة ()withFoo.

مساعدو الاستجابة Response Helpers

يتضمن كائن استجابة الخادم Server Response object (اختصارًا res) مجموعة من الدوال المساعدة التي تشبه مساعدي Express.js تحسّن من تجربة المطوّر وتزيد سرعة إنشاء وصلات API جديدة. إليك بعض الدوال المساعدة:

• res.status(code): دالة لضبط رمز الحالة التي يرد بها الخادم، وينبغي أن تكون رمز صحيح لحالة HTTP.
• res.json(body): دالة لإرسال استجابة بتنسيق JSON، وينبغي أن يكون جسم الطلب كائنًا قابلًا للسلسلة serializable object (أي يمكن تحويل صيغته إلى شكل آخر).
• res.send(body): دالة لإرسال استجابة HTTP التي قد تكون body أو string أو object أو Buffer.
• res.redirect([status,] path): دالة لتحويل الطلب إلى مسار أو عنوان URL محدد. ينبغي أن يكون المعامل status عبارة رمز حالة HTTP صحيح، وستكون قيمته الافتراضية "307" (إعادة توجيه مؤقت) إن لم تُحدد هذه القيمة.
• res.unstable_revalidate(urlPath): دالة لإعادة التحقق من الصفحة حين الطلب باستخدام الدالة getStaticProps. ينبغي أن يكون المعامل urlPath سلسلة نصية.

ضبط رمز الحالة في الاستجابة

يمكنك ضبط رمز الحالة عندما تعيد الاستجابة إلى العميل. يضبط المثال التالي قيمة رمز الحالة على "200" (كل شيء على ما يرام ok) ويعيد رسالة على شكل خاصية message قيمتها "Next.js ترحب بك!":

export default function handler(req, res) {
  res.status(200).json({ message: '!ترحب بك Next.js' })
}

إرسال استجابة بتنسيق JSON

يمكنك إعادة الاستجابة إلى العميل بتنسيق JSON، لكن ينبغي أن تكون الاستجابة كائنًا قابلًا للسلسلة. وقد ترغب في التطبيقات الحقيقية أن تخبر العميل بحالة طلبه وفقًا لاستجابة الوصلة endpoint التي طلبها.

يرسل المثال التالي الاستجابة بتنسيق JSON مع رمز الحالة "200" ونتيجة العملية غير المتزامنة. لاحظ وجود الشيفرة في كتلة try...catch لمعالجة أية أخطاء قد تحدث، وذلك بإرسال رمز الحالة ورسالة خطأ إلى العميل:

export default async function handler(req, res) {
  try {
    const result = await someAsyncOperation()
    res.status(200).json({ result })
  } catch (err) {
    res.status(500).json({ error: 'failed to load data' })
  }
}

إرسال استجابة HTTP

تُرسل وفق الآلية نفسها التي تُرسل فيها الاستجابة بتنسيق JSON، لكن الفرق الوحيد أنّ جسم الاستجابة قد يكون نصيًا string أو على شكل كائن object أو مخزن من البايتات Buffer.

يرسل المثال التالي استجابة HTTP مع رمز الحالة "200" ونتيجة العملية غير المتزامنة:

export default async function handler(req, res) {
  try {
    const result = await someAsyncOperation()
    res.status(200).send({ result })
  } catch (err) {
    res.status(500).send({ error: 'failed to fetch data' })
  }
}

تحويل الاستجابة إلى مسار أو عنوان URL محدد

قد ترغب مثلًا في تحويل العميل إلى مسار أو عنوان محدد عندما ينقر زر إرسال نموذج form. لاحظ كيف يوجّه المثال التالي العميل إلى المسار / عندما يُرسل النموذج بنجاح:

export default async function handler(req, res) {
  const { name, message } = req.body
  try {
    await handleFormInputAsync({ name, message })
    res.redirect(307, '/')
  } catch (err) {
    res.status(500).send({ error: 'failed to fetch data' })
  }
}

إضافة أنواع TypeScript

بإمكانك أن تجعل معالج الاستجابة أكثر أمانًا من ناحية النوع الذي يعيده بإدراج النوعين NextApiRequest و NextApiResponse من next كما يمكنك تحديد نوع البيانات التي ستعديدها في الاستجابة:

import type { NextApiRequest, NextApiResponse } from 'next'

type ResponseData = {
  message: string
}

export default function handler(
  req: NextApiRequest,
  res: NextApiResponse<ResponseData>
) {
  res.status(200).json({ message: 'Hello from Next.js!' })
}

ملاحظة: نوع الكائن body في NextApiRequest هو any بسبب أن العميل يمكن أن يضمن في جسم الطلب أي شيء، لذا يجب عليك التحقق من نوعه إن كنت تتوقع شيئًا محددًا من العميل قبل التعامل معه.

لمعلومات أكثر، راجع توثيق استخدام TypeScript في Next.js.

أمثلة

• Basic API Routes
• API Routes with GraphQL
• API Routes with REST
• API Routes with CORS
• API Routes Request Helpers

المصادر

• صفحات API Routes من توثيق Next.js الرسمي.