مسارات الواجهة البرمجية API Routes في Next.js

تٌعد مسارات الواجهة البرمجية 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.

استخدام وجهات API المعتمدة على المشغل المتقدم Edge

تتيح لك وجهات API المعتمدة على المشغل المتقدم edge runtime بناء واجهات برمجية API عالية الأداء باستخدام Next.js. وتُعد الواجهات البرمجية API المبنية باستخدام المكتبة Edge Runtime أسرع من تلك المبنية باستخدام Node.js. يأتي التحسن في أداء هذه الواجهات من وجود بعض التقييدات مثل عدم القدرة على الوصول إلى واجهات Node.js البرمجية الأصلية. إذ تُبنى الواجهات البرمجية في هذه الحالة باستخدام وجهات API المتقدمة وفقًا لمعايير واجهات الويب البرمجية Web APIs.

يرتبط كل ملف ضمن المجلد pages/api بالوجهة */api/ وستتعامل معه Next.js على أنها واجهة برمجية بدلًا من كونها صفحات. تُعد هذه الواجهات تجمّعات في طرف الخادم ولن تزيد حجم الحزمة في طرف العميل.

أمثلة

مثال تمهيدي

export const config = {
  runtime: 'edge',
}

export default (req) => new Response('Hello world!')

استجابة بتنسيق JSON

import type { NextRequest } from 'next/server'

export const config = {
  runtime: 'edge',
}

export default async function handler(req: NextRequest) {
  return new Response(
    JSON.stringify({
      name: 'Jim Halpert',
    }),
    {
      status: 200,
      headers: {
        'content-type': 'application/json',
      },
    }
  )
}

التحكم بحجم المخزن المؤقت

import type { NextRequest } from 'next/server'

export const config = {
  runtime: 'edge',
}

export default async function handler(req: NextRequest) {
  return new Response(
    JSON.stringify({
      name: 'Jim Halpert',
    }),
    {
      status: 200,
      headers: {
        'content-type': 'application/json',
        'cache-control': 'public, s-maxage=1200, stale-while-revalidate=600',
      },
    }
  )
}

معاملات استعلام

import type { NextRequest } from 'next/server'

export const config = {
  runtime: 'edge',
}

export default async function handler(req: NextRequest) {
  const { searchParams } = new URL(req.url)
  const email = searchParams.get('email')
  return new Response(email)
}

توجيه الترويسات

import { type NextRequest } from 'next/server'

export const config = {
  runtime: 'edge',
}

export default async function handler(req: NextRequest) {
  const authorization = req.cookies.get('authorization')?.value
  return fetch('https://backend-api.com/api/protected', {
    method: req.method,
    headers: {
      authorization,
    },
    redirect: 'manual',
  })
}

تهيئة إعداد المناطق من أجل نشر التطبيق

قد ترغب في حصر الدوال التي تُنفّذ عن طريقة المشغّل الحدودي edge بمناطق معينة عند نشر التطبيق حتى تبقى قريبًا من مصدر البيانات وتتأكد من تحقيق زمن استجابة أسرع وذلك باستخدام الطريقة التالية:

import { NextResponse } from 'next/server'

export const config = {
  regions: ['sfo1', 'iad1'], // defaults to 'all'
}

export default async function handler(req: NextRequest) {
  const myData = await getNearbyData()
  return NextResponse.json(myData)
}

يُتاح هذا الإعداد للنسخ 12.3.2 وما بعد من Next.js

الاختلافات بين وجهات API

تستخدم وجهات API المتقدمة (التي ينفذها المشغّل edge) المكتبة Edge Runtime، بينما تستخدم وجهات API النمطية مشغل Node.js. ويمكن لوجهات API المتقدمة سحب الاستجابات من الخادم ومن ثم تعمل بعد الوصول إلى الملفات المخزنة مؤقتًا مثل ملفات HTML و CSS وجافاسكربت. يمكن لهذه الطريقة أن تساعد في تحسين الأداء من خلال تقليل مؤشر "زمن وصول البايت الأول TTFB".

ملاحظة: لا يتيح استخدام Edge Runtime مع الدالة getServerSideProps إمكانية الوصول إلى كائن الاستجابة. فإن أردت الوصول إلى الكائن res لا بد من استخدام مشغّل Node.js runtime عن طريق الإعداد التالي: 'runtime: 'nodejs.

أمثلة

المصادر

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

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

محاذير

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

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

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

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

محاذير

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

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

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

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

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

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

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

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

إضافة أنواع TypeScript

استخدام وجهات API المعتمدة على المشغل المتقدم Edge

أمثلة

مثال تمهيدي

استجابة بتنسيق JSON

التحكم بحجم المخزن المؤقت

معاملات استعلام

توجيه الترويسات

تهيئة إعداد المناطق من أجل نشر التطبيق

الاختلافات بين وجهات API

أمثلة

المصادر

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