Node.js + ExpressでREST APIを構築する際のレスポンス設定: 具体的な例

2024-05-23

Node.js, Expressを使ったREST APIにおけるレスポンスステータスとJSONコンテンツの適切な設定方法

ステータスコードの設定

HTTPステータスコードは、リクエストに対する結果を簡潔に伝えるものです。REST APIでは、以下のような一般的なステータスコードが用いられます。

200 OK: リクエストが成功し、要求された情報が返却されたことを示します。
201 Created: 新しいリソースが作成されたことを示します。
400 Bad Request: リクエストが不正な形式であることを示します。
404 Not Found: 要求されたリソースが見つからないことを示します。
500 Internal Server Error: サーバー側で予期しないエラーが発生したことを示します。

Expressでは、res.status()メソッドを用いてステータスコードを設定できます。以下は、ステータスコード200を設定する例です。

res.status(200).send('Success!');

JSONコンテンツの設定

JSON形式のデータは、JavaScript Object Notationの略称で、軽量かつ人間可読性の高いデータ表現形式です。REST APIでは、JSONを用いてデータをやり取りするのが一般的です。

Expressでは、res.json()メソッドを用いてJSONコンテンツを設定できます。以下は、JSONオブジェクトを返却する例です。

const data = { message: 'Hello, world!' };
res.json(data);

具体的な例

以下は、GETリクエストに対してJSONデータを含むレスポンスを返す例です。

app.get('/users/:id', (req, res) => {
  const userId = req.params.id;
  const user = getUserById(userId);

  if (user) {
    res.json(user);
  } else {
    res.status(404).send('User not found');
  }
});

この例では、getUserById()関数で指定されたIDを持つユーザー情報を取得します。ユーザーが見つかった場合は、res.json()を用いてJSON形式で情報を返します。見つからない場合は、ステータスコード404を設定してエラーメッセージを返します。

Node.jsとExpressを用いてREST APIを構築する際、レスポンスステータスとJSONコンテンツを適切に設定することは重要です。res.status()とres.json()メソッドを活用することで、クライアントへの情報伝達とエラー処理を効果的に行うことができます。

ユーザー情報の取得API

このAPIは、GET /users/:idリクエストに対して、指定されたIDを持つユーザー情報をJSON形式で返します。

const express = require('express');
const app = express();
const port = 3000;

const users = [
  { id: 1, name: 'Taro Yamada' },
  { id: 2, name: 'Hanako Sato' },
  { id: 3, name: 'Jiro Suzuki' },
];

app.get('/users/:id', (req, res) => {
  const userId = parseInt(req.params.id);
  const user = users.find(user => user.id === userId);

  if (user) {
    res.json(user);
  } else {
    res.status(404).send('User not found');
  }
});

app.listen(port, () => {
  console.log(`Server listening on port ${port}`);
});

新規ユーザーの作成API

このAPIは、POST /usersリクエストに対して、新しいユーザー情報をJSON形式で受け取り、データベースに保存します。

app.post('/users', (req, res) => {
  const newUser = req.body;

  if (!newUser.name) {
    res.status(400).send('Bad Request: name is required');
    return;
  }

  // 新規ユーザーをデータベースに保存
  // ...

  res.status(201).send('User created');
});

app.put('/users/:id', (req, res) => {
  const userId = parseInt(req.params.id);
  const updatedUser = req.body;

  const existingUser = users.find(user => user.id === userId);

  if (!existingUser) {
    res.status(404).send('User not found');
    return;
  }

  // ユーザー情報を更新
  // ...

  res.json(updatedUser);
});

app.delete('/users/:id', (req, res) => {
  const userId = parseInt(req.params.id);

  const index = users.findIndex(user => user.id === userId);

  if (index !== -1) {
    users.splice(index, 1);
    res.status(204).send();
  } else {
    res.status(404).send('User not found');
  }
});

これらのサンプルコードは、REST APIにおけるレスポンスステータスとJSONコンテンツ設定の基本的な概念を理解するためのものです。実際のアプリケーションでは、より複雑なロジックやエラー処理が必要となる場合があります。

Node.js + ExpressでREST APIのレスポンスステータスとJSONコンテンツを設定するその他の方法

エラーハンドリングミドルウェアの使用

Expressは、エラーハンドリングミドルウェアを使用して、エラー発生時のレスポンスを統一的に処理することができます。これにより、コードをより簡潔かつ保守しやすくなります。

以下は、express-error-handlerミドルウェアを用いた例です。

const express = require('express');
const app = express();
const errorHandler = require('express-error-handler');

// ...

app.use(errorHandler());

app.get('/users/:id', (req, res, next) => {
  const userId = parseInt(req.params.id);

  // ユーザー情報の取得
  // ...

  if (!user) {
    next(new Error('User not found'));
  }

  res.json(user);
});

// エラーハンドラー
app.use((err, req, res, next) => {
  console.error(err.stack);

  if (res.headersSent) {
    return next(err);
  }

  res.status(err.statusCode || 500).send({ message: err.message });
});

この例では、next(new Error('User not found'))を使用してエラーをハンドラーに伝えています。ハンドラーは、エラーメッセージと適切なステータスコードを含むJSONレスポンスを返します。

カスタムレスポンスクラスを作成することで、レスポンスステータスとJSONコンテンツをより柔軟に制御することができます。

以下は、カスタムレスポンスクラスを用いた例です。

class ApiResponse {
  constructor(data, statusCode = 200) {
    this.data = data;
    this.statusCode = statusCode;
  }

  send(res) {
    res.status(this.statusCode).json(this.data);
  }
}

app.get('/users/:id', (req, res) => {
  const userId = parseInt(req.params.id);
  const user = getUserById(userId);

  if (user) {
    new ApiResponse(user).send(res);
  } else {
    new ApiResponse({ message: 'User not found' }, 404).send(res);
  }
});

この例では、ApiResponseクラスを使用して、レスポンスデータとステータスコードをカプセル化しています。send()メソッドを用いて、レスポンスをクライアントに送信します。

Promise APIの使用

ExpressはPromise APIに対応しており、非同期処理をより簡潔に記述することができます。

以下は、Promise APIを用いた例です。

app.get('/users/:id', async (req, res) => {
  const userId = parseInt(req.params.id);

  try {
    const user = await getUserById(userId);
    res.json(user);
  } catch (err) {
    if (err.statusCode) {
      res.status(err.statusCode).send(err.message);
    } else {
      res.status(500).send('Internal Server Error');
    }
  }
});