Chore: api-routes/response-helpers の更新

docs/api-routes/response-helpers.md

@@ -1,27 +1,106 @@
 ---
-description: APIルートには、レスポンスのためのExpress.jsライクなメソッドが用意されており、新しいAPIエンドポイントの作成に役立ちます。どのように動作するか学んでいきましょう。
+description: API Routes include a set of Express.js-like methods for the response to help you creating new API endpoints. Learn how it works here.
 ---
 
-# レスポンスヘルパー
+# Response Helpers
 
-<details open>
-  <summary><b>例</b></summary>
-  <ul>
-    <li><a href="https://github.com/vercel/next.js/tree/canary/examples/api-routes">基本的なAPIルート</a></li>
-    <li><a href="https://github.com/vercel/next.js/tree/canary/examples/api-routes-rest">RESTによるAPIルート</a></li>
-  </ul>
-</details>
+The [Server Response object](https://nodejs.org/api/http.html#http_class_http_serverresponse), (often abbreviated as `res`) includes a set of Express.js-like helper methods to improve the developer experience and increase the speed of creating new API endpoints.
 
-レスポンス (`res`) には、Express.js ライクなメソッドのセットが用意されています。これらは、より良い開発者体験を提供し、より手早く API エンドポイントを作成できます。次の例を見てみましょう:
+The included helpers are:
+
+- `res.status(code)` - A function to set the status code. `code` must be a valid [HTTP status code](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes)
+- `res.json(body)` - Sends a JSON response. `body` must be a [serializable object](https://developer.mozilla.org/en-US/docs/Glossary/Serialization)
+- `res.send(body)` - Sends the HTTP response. `body` can be a `string`, an `object` or a `Buffer`
+- `res.redirect([status,] path)` - Redirects to a specified path or URL. `status` must be a valid [HTTP status code](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes). If not specified, `status` defaults to "307" "Temporary redirect".
+- `res.unstable_revalidate(urlPath)` - [Revalidate a page on demand](/docs/basic-features/data-fetching/incremental-static-regeneration.md#on-demand-revalidation-beta) using `getStaticProps`. `urlPath` must be a `string`.
+
+## Setting the status code of a response
+
+When sending a response back to the client, you can set the status code of the response.
+
+The following example sets the status code of the response to `200` (`OK`) and returns a `message` property with the value of `Hello from Next.js!` as a JSON response:
 
 ```js
-export default (req, res) => {
-  res.status(200).json({ name: 'Next.js' });
-};
+export default function handler(req, res) {
+  res.status(200).json({ message: 'Hello from Next.js!' })
+}
 ```
 
-用意されているメソッドは以下の通りです:
+## Sending a JSON response
+
+When sending a response back to the client you can send a JSON response, this must be a [serializable object](https://developer.mozilla.org/en-US/docs/Glossary/Serialization).
+In a real world application you might want to let the client know the status of the request depending on the result of the requested endpoint.
+
+The following example sends a JSON response with the status code `200` (`OK`) and the result of the async operation. It's contained in a try catch block to handle any errors that may occur, with the appropriate status code and error message caught and sent back to the client:
+
+```js
+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' })
+  }
+}
+```
+
+## Sending a HTTP response
+
+Sending an HTTP response works the same way as when sending a JSON response. The only difference is that the response body can be a `string`, an `object` or a `Buffer`.
+
+The following example sends a HTTP response with the status code `200` (`OK`) and the result of the async operation.
+
+```js
+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' })
+  }
+}
+```
+
+## Redirects to a specified path or URL
+
+Taking a form as an example, you may want to redirect your client to a specified path or URL once they have submitted the form.
+
+The following example redirects the client to the `/` path if the form is successfully submitted:
+
+```js
+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' })
+  }
+}
+```
+
+## Adding TypeScript types
+
+You can make your response handlers more type-safe by importing the `NextApiRequest` and `NextApiResponse` types from `next`, in addition to those, you can also type your response data:
+
+```ts
+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!' })
+}
+```
+
+To view more examples using types, check out the [TypeScript documentation](/docs/basic-features/typescript.md#api-routes).
+
+If you prefer to view your examples within a real projects structure you can checkout our examples repository:
 
-- `res.status(code)` -  ステータスコードを設定するための関数です。 `code` は正しい[HTTPステータスコード](https://ja.wikipedia.org/wiki/HTTP%E3%82%B9%E3%83%86%E3%83%BC%E3%82%BF%E3%82%B9%E3%82%B3%E3%83%BC%E3%83%89)である必要があります。
-- `res.json(json)` - JSON レスポンスを送信します。`json` は正しい JSON オブジェクトである必要があります。
-- `res.send(body)` - HTTP レスポンスを送信します。 `body` は `string` か `object` 、または `Buffer` である必要があります。
+- [Basic API Routes](https://github.com/vercel/next.js/tree/canary/examples/api-routes)
+- [API Routes with REST](https://github.com/vercel/next.js/tree/canary/examples/api-routes-rest)