API Routes

Bilmekte fayda var: Uygulama Yönlendiricisi kullanıyorsanız API Rotaları yerine Sunucu Bileşenleri veya Rota İşleyicileri kullanabilirsiniz.

API rotaları, Next.js ile genel bir API oluşturmak için bir çözüm sağlar.

pages/api klasörü içindeki herhangi bir dosya /api/* ile eşleştirilir ve page yerine bir API uç noktası olarak değerlendirilir. Bunlar yalnızca sunucu tarafı paketleridir ve istemci tarafı paket boyutunuzu artırmaz.

Örneğin, aşağıdaki API rotası 200 durum koduyla bir JSON yanıtı döndürür:

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!' })
}

Bildiğim iyi oldu:

• API Rotaları CORS başlıklarını belirtmez, yani varsayılan olarak yalnızca aynı kaynak lıdırlar. İstek işleyicisini CORS istek yardımcıları ile sararak bu davranışı özelleştirebilirsiniz.

• API Rotaları statik dışa aktarmalarla kullanılamaz. Ancak, Uygulama Yönlendiricisindeki Rota İşleyicileri kullanılabilir.

  • API Rotaları next.config.js adresindeki pageExtensions yapılandırmasından etkilenecektir.

Parameters

export default function handler(req: NextApiRequest, res: NextApiResponse) {
  // ...
}

• req: Bir http.IncomingMessage örneği
• res: Bir http.ServerResponse örneği

HTTP Methods

Bir API rotasında farklı HTTP yöntemlerini işlemek için istek işleyicinizde req.method adresini aşağıdaki gibi kullanabilirsiniz:

import type { NextApiRequest, NextApiResponse } from 'next'
 
export default function handler(req: NextApiRequest, res: NextApiResponse) {
  if (req.method === 'POST') {
    // Process a POST request
  } else {
    // Handle any other HTTP method
  }
}

Request Helpers

API Routes, gelen isteği ayrıştıran yerleşik istek yardımcıları sağlar (req):

• req.cookies - İstek tarafından gönderilen çerezleri içeren bir nesne. Varsayılan değer {}
• req.query - Sorgu dizesini içeren bir nesne . Varsayılan değer {}
• req.body - content-type tarafından ayrıştırılan gövdeyi içeren bir nesne veya herhangi bir gövde gönderilmediyse null

Custom config

Her API Rotası, aşağıdaki varsayılan yapılandırmayı değiştirmek için bir config nesnesini dışa aktarabilir:

export const config = {
  api: {
    bodyParser: {
      sizeLimit: '1mb',
    },
  },
  // Specifies the maximum allowed duration for this function to execute (in seconds)
  maxDuration: 5,
}

bodyParser otomatik olarak etkinleştirilir. Gövdeyi bir Stream olarak tüketmek istiyorsanız veya raw-bodybunu false olarak ayarlayabilirsiniz.

Otomatik bodyParsing adresini devre dışı bırakmak için bir kullanım örneği, örneğin GitHub adresinden bir web kancası isteğinin ham gövdesini doğrulamanıza izin vermektir.

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

bodyParser.sizeLimit ayrıştırılan gövde için izin verilen maksimum boyuttur, bytes tarafından desteklenen herhangi bir formatta , bu şekilde:

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

externalResolver sunucuya bu rotanın express veya connect gibi harici bir çözümleyici tarafından işlendiğini söyleyen açık bir bayraktır. Bu seçeneğin etkinleştirilmesi, çözülmemiş istekler için uyarıları devre dışı bırakır.

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

responseLimit otomatik olarak etkinleştirilir ve bir API Routes'un yanıt gövdesi 4 MB'ın üzerinde olduğunda uyarı verir.

Next.js'yi sunucusuz bir ortamda kullanmıyorsanız ve bir CDN veya özel medya barındırıcısı kullanmamanın performans üzerindeki etkilerini anlıyorsanız, bu sınırı false olarak ayarlayabilirsiniz.

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

responseLimit bayt sayısını veya bytes tarafından desteklenen herhangi bir dize biçimini de alabilir, örneğin 1000, '500kb' veya '3mb'. Bu değer, bir uyarı görüntülenmeden önce maksimum yanıt boyutu olacaktır. Varsayılan değer 4MB'dir. (yukarıya bakın)

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

Response Helpers

Sunucu Yanıtı nesnesi, (genellikle res olarak kısaltılır) geliştirici deneyimini iyileştirmek ve yeni API uç noktaları oluşturma hızını artırmak için bir dizi Express.js benzeri yardımcı yöntem içerir.

Dahil edilen yardımcılar şunlardır:

• res.status(code) - Durum kodunu ayarlamak için bir işlev. code geçerli bir HTTP durum kodu olmalıdır
• res.json(body) - Bir JSON yanıtı gönderir. body serileştirilebilir bir nesne olmalıdır
• res.send(body) - HTTP yanıtı gönderir. body bir string, bir object veya bir Buffer
• res.redirect([status,] path) - Belirtilen bir yola veya URL'ye yönlendirir. status geçerli bir HTTP durum kodu olmalıdır. Belirtilmezse, status varsayılan olarak "307" "Geçici yönlendirme" değerini alır.
• res.revalidate(urlPath) - getStaticProps kullanarak talep üzerine bir sayfayı yeniden doğrulayın. urlPath bir string olmalıdır.

Setting the status code of a response

İstemciye bir yanıt geri gönderirken, yanıtın durum kodunu ayarlayabilirsiniz.

Aşağıdaki örnek, yanıtın durum kodunu 200 (OK) olarak ayarlar ve JSON yanıtı olarak Hello from Next.js! değerine sahip bir message özelliği döndürür:

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!' })
}

Sending a JSON response

İstemciye bir yanıt gönderirken bir JSON yanıtı gönderebilirsiniz, bu serileştirilebilir bir nesne olmalıdır . Gerçek dünyadaki bir uygulamada, istenen uç noktanın sonucuna bağlı olarak istemciye isteğin durumunu bildirmek isteyebilirsiniz.

Aşağıdaki örnek, 200 (OK) durum kodunu ve asenkron işlemin sonucunu içeren bir JSON yanıtı gönderir. Oluşabilecek herhangi bir hatayı ele almak için bir try catch bloğu içinde yer alır, uygun durum kodu ve hata mesajı yakalanır ve istemciye geri gönderilir:

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

Sending a HTTP response

Bir HTTP yanıtı göndermek, bir JSON yanıtı göndermekle aynı şekilde çalışır. Tek fark, yanıt gövdesinin bir string, bir object veya bir Buffer olabilmesidir.

Aşağıdaki örnek, 200 (OK) durum kodunu ve asenkron işlemin sonucunu içeren bir HTTP yanıtı gönderir.

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

Redirects to a specified path or URL

Örnek olarak bir formu ele alırsak, müşterinizi formu gönderdikten sonra belirli bir yola veya URL'ye yönlendirmek isteyebilirsiniz.

Aşağıdaki örnek, form başarıyla gönderilirse istemciyi / yoluna yönlendirir:

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

Adding TypeScript types

NextApiRequest ve NextApiResponse türlerini next adresinden içe aktararak API Rotalarınızı daha güvenli hale getirebilirsiniz, bunlara ek olarak yanıt verilerinizi de yazabilirsiniz:

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!' })
}

Bilmekte fayda var: İstemci herhangi bir yük içerebileceğinden NextApiRequest gövdesi any şeklindedir. Kullanmadan önce gövdenin türünü/şeklini çalışma zamanında doğrulamalısınız.

Dynamic API Routes

API Rotaları dinamik rotaları destekler ve pages/ için kullanılan aynı dosya adlandırma kurallarını izler.

import type { NextApiRequest, NextApiResponse } from 'next'
 
export default function handler(req: NextApiRequest, res: NextApiResponse) {
  const { pid } = req.query
  res.end(`Post: ${pid}`)
}

Şimdi, /api/post/abc adresine yapılan bir istek şu metinle yanıtlanacaktır: Post: abc.

Catch all API routes

API Rotaları, parantezlerin içine üç nokta (...) eklenerek tüm yolları yakalayacak şekilde genişletilebilir. Örneğin:

• pages/api/post/[...slug].js /api/post/a ile eşleşir, aynı zamanda /api/post/a/b, /api/post/a/b/c vb. ile de eşleşir.

Bilmekte fayda var: slug dışında başka isimler de kullanabilirsiniz, örneğin: [...param]

Eşleşen parametreler sayfaya bir sorgu parametresi (örnekteslug ) olarak gönderilecek ve her zaman bir dizi olacaktır, bu nedenle /api/post/a yolu aşağıdaki query nesnesine sahip olacaktır:

{ "slug": ["a"] }

Ve /api/post/a/b, ve eşleşen diğer herhangi bir yol durumunda, diziye aşağıdaki gibi yeni parametreler eklenecektir:

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

Örneğin:

import type { NextApiRequest, NextApiResponse } from 'next'
 
export default function handler(req: NextApiRequest, res: NextApiResponse) {
  const { slug } = req.query
  res.end(`Post: ${slug.join(', ')}`)
}

Şimdi, /api/post/a/b/c adresine yapılan bir istek şu metinle yanıtlanacaktır: Post: a, b, c.

Optional catch all API routes

Tüm rotaları yakala parametresi çift parantez ([[...slug]]) içine dahil edilerek isteğe bağlı hale getirilebilir.

Örneğin, pages/api/post/[[...slug]].js adresi /api/post, /api/post/a, /api/post/a/b ve benzeri adreslerle eşleşecektir.

Tümünü yakala ve isteğe bağlı tümünü yakala rotaları arasındaki temel fark, isteğe bağlı olduğunda parametresi olmayan rotanın da eşleştirilmesidir (yukarıdaki örnekte/api/post ).

query nesneleri aşağıdaki gibidir:

{ } // GET `/api/post` (empty object)
{ "slug": ["a"] } // `GET /api/post/a` (single-element array)
{ "slug": ["a", "b"] } // `GET /api/post/a/b` (multi-element array)

Caveats

• Önceden tanımlanmış API rotaları dinamik API rotalarına göre ve dinamik API rotaları tüm API rotalarını yakalamaya göre önceliklidir. Aşağıdaki örneklere bir göz atın:
  • pages/api/post/create.js - Eşleşecek /api/post/create
  • pages/api/post/[pid].js - /api/post/1, /api/post/abc vb. ile eşleşecektir. Ama değil /api/post/create
  • pages/api/post/[...slug].js - /api/post/1/2, /api/post/a/b/c vb. ile eşleşecektir. Ancak /api/post/create ile eşleşmez, /api/post/abc

Edge API Routes

Edge Runtime ile API Routes kullanmak istiyorsanız, App Router'ı aşamalı olarak benimsemenizi ve bunun yerine Route Handlers kullanmanızı öneririz.

Route Handlers işlev imzası izomorfiktir, yani aynı işlevi hem Edge hem de Node.js çalışma zamanları için kullanabilirsiniz.