API 쿼리 매개변수는 서버에 추가 정보를 보내기 위해 API 요청의 URL에 추가되는 키-값 쌍입니다. 이를 통해 클라이언트(예: 웹 브라우저 또는 애플리케이션)가 서버에 요청할 때 특정 기준을 지정하거나 데이터를 전달할 수 있습니다.

쿼리 매개변수는 URL 끝에 물음표(?) 뒤에 추가됩니다. 각 매개변수는 키-값 쌍으로, 키와 값은 등호(=)로 구분됩니다. 쿼리 매개변수가 여러 개인 경우 앰퍼샌드(&)로 구분됩니다.

쿼리 매개변수 사용 방법:
데이터 필터링: 클라이언트는 쿼리 매개변수를 사용하여 원하는 데이터를 필터링할 수 있습니다. 예를 들어, ?category=books는 "books" 카테고리의 항목만 반환하도록 서버에 지시할 수 있습니다.

페이지 매기기: 쿼리 매개변수는 API 요청의 페이지 매기기에 자주 사용되므로 클라이언트가 가져올 결과 페이지와 페이지당 항목 수를 지정할 수 있습니다. 예: ?page=2&limit=10.

정렬 및 순서 지정: 쿼리 매개변수를 사용하여 데이터 정렬 방법을 지정할 수 있습니다. 예를 들어 ?sort=price&order=asc는 가격을 기준으로 오름차순으로 정렬된 항목을 반환하도록 서버에 지시할 수 있습니다.

검색어 전달: API는 클라이언트가 데이터를 검색할 수 있도록 쿼리 매개변수를 사용하는 경우가 많습니다. 예를 들어, ?search=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=John은 { "message": "안녕하세요, John!"을 반환합니다. }
/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은 { "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. 쿼리 매개변수를 사용한 페이지 매김 이 핸들러는 페이지 및 제한에 대한 쿼리 매개변수를 사용하여 페이지 매김을 구현하는 방법을 보여줍니다.

// 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 는 { "items": ["Item 6", "Item 7", "Item 8", "Item 9", "Item 10"]과 같은 다음 5개 항목을 반환합니다. }
/api/items (기본값)는 { "items": ["Item 1", "Item 2", ..., "Item 10"] }

이 예는 단일 또는 다중 매개변수, 선택적 값, 배열, 페이지 매김과 같은 일반적인 패턴을 포함하여 Next.js API 경로에서 쿼리 매개변수를 사용하는 유연성을 보여줍니다.