API クエリ パラメーターは、サーバーに追加情報を送信するために API リクエストの URL に追加されるキーと値のペアです。これにより、クライアント (Web ブラウザーやアプリケーションなど) は、サーバーにリクエストを行うときに特定の基準を指定したり、データを渡したりすることができます。

クエリ パラメータは URL の末尾の疑問符 (?) の後に追加されます。各パラメーターはキーと値のペアであり、キーと値は等号 (=) で区切られています。複数のクエリ パラメータがある場合は、アンパサンド (&) で区切られます。

クエリパラメータの使用方法:
データのフィルタリング: クライアントはクエリ パラメータを使用して、必要なデータをフィルタリングできます。たとえば、?category=books は、「books」カテゴリからのアイテムのみを返すようにサーバーに指示する場合があります。

ページネーション: クエリ パラメーターは API リクエストのページネーションによく使用され、クライアントが結果のどのページを取得するか、およびページごとのアイテム数を指定できるようにします。例: ?page=2&limit=10.

並べ替えと順序付け: クエリ パラメーターを使用して、データの並べ替え方法を指定できます。たとえば、?sort=price&order=asc は、価格でソートされたアイテムを昇順で返すようにサーバーに指示できます。

検索語の受け渡し: API は多くの場合、クライアントがデータを検索できるようにするためにクエリ パラメーターを使用します。たとえば、?search=laptop を使用すると、用語「laptop」に一致するすべての製品を検索できます。

クエリ パラメーターは柔軟性が高く、API の設計方法に応じてさまざまな方法で使用できます。これらにより、クライアントとサーバー間の動的な対話が可能になり、カスタマイズされたデータのリクエストが容易になります。

1. 基本的なクエリパラメータの処理 この API ハンドラーは、クエリ パラメーターを抽出して使用して、パーソナライズされた挨拶を返す方法を示します。

// pages/api/greet.js

export default function handler(req, res) {
  const { name } = req.query; // Get the 'name' query parameter
  const greeting = name ? `Hello, ${name}!` : 'Hello, stranger!';

  res.status(200).json({ message: greeting });
}

使用例:
/api/greet?name=ジョンは { "message": "こんにちは、ジョン!" を返します。 }
/api/greet は { "message": "こんにちは、見知らぬ人!" を返します。 }

1. 複数のクエリパラメータ この例では、API ハンドラーは複数のクエリ パラメーターを抽出し、ユーザー入力に基づいてフォーマットされた応答を返します。

// pages/api/user.js

export default function handler(req, res) {
  const { name, age } = req.query; // Get 'name' and 'age' query parameters

  if (!name || !age) {
    res.status(400).json({ error: 'Name and age are required' });
    return;
  }

  res.status(200).json({ message: `User ${name} is ${age} years old.` });
}

使用例:
/api/user?name=Jane&age=28 は { "message": "ユーザー Jane は 28 歳です。" を返します。 }
/api/user?name=Jane は { "error": "名前と年齢が必要です" }

1. デフォルト値を含むオプションのクエリパラメータ この例では、パラメーターが欠落している場合にデフォルト値を提供することで、オプションのクエリ パラメーターを処理する方法を示します。

// pages/api/score.js

export default function handler(req, res) {
  const { player = 'Anonymous', score = '0' } = req.query; // Default values if missing

  res.status(200).json({ message: `${player} scored ${score} points!` });
}

使用例:
/api/score?player=Alex&score=100 will return { "message": "Alex は 100 点を獲得しました!" }
/api/score は { "message": "匿名さんは 0 点を獲得しました!" を返します。 }

1. クエリパラメータでの配列の処理 Next.js では、クエリ パラメーターを配列として渡すことができます。この例では、値の配列を処理する方法を示します。

// pages/api/tags.js

export default function handler(req, res) {
  const { tags } = req.query; // Get 'tags' query parameter (array)

  if (!tags) {
    res.status(400).json({ error: 'Tags are required' });
    return;
  }

  res.status(200).json({ message: `You have selected these tags: ${tags.join(', ')}` });
}

使用例:
/api/tags?tags=javascript&tags=react は { "message": "次のタグを選択しました: javascript、react" }
を返します /api/tags は { "error": "タグが必要です" }

1. クエリパラメータを使用したページネーション このハンドラーは、page および limit のクエリ パラメーターを使用してページネーションを実装する方法を示します。

// pages/api/items.js

export default function handler(req, res) {
  const { page = 1, limit = 10 } = req.query; // Default values for page and limit
  const startIndex = (page - 1) * limit;
  const endIndex = startIndex   Number(limit);

  // Dummy data for demonstration
  const items = Array.from({ length: 100 }, (_, i) => `Item ${i   1}`);
  const paginatedItems = items.slice(startIndex, endIndex);

  res.status(200).json({
    currentPage: page,
    perPage: limit,
    items: paginatedItems,
  });
}

使用例:
/api/items?page=2&limit=5 は、次の 5 つのアイテムを返します。例: { "items": ["Item 6", "Item 7", "Item 8", "Item 9", "Item 10"] }
/api/items (デフォルト値) は、{ "items": ["Item 1", "Item 2", ..., "Item 10"] }

これらの例は、Next.js API ルートでクエリ パラメーターを使用する柔軟性を示し、単一または複数のパラメーター、オプションの値、配列、ページネーションなどの一般的なパターンをカバーしています。