https://docs.strapi.io/cms/api/document-service#parameters-5

Strapi API Query Parameters

Strapi의 API에서 사용할 수 있는 주요 쿼리 파라미터(Query Parameters) 옵션들을 정리했습니다.

1. populate (관계 데이터 포함)

관계 데이터를 가져오기 위해 사용됩니다.

예제:

const query = qs.stringify({
  populate: 'author'
});
const url = `http://localhost:1337/api/posts?${query}`;

???? populate: 'author' → Post와 연결된 Author 데이터를 포함.

특정 필드만 포함:

const query = qs.stringify({
  populate: { author: { fields: ['name', 'email'] } }
}, { encodeValuesOnly: true });

2. fields (특정 필드만 선택)

가져올 필드를 제한하여 응답 크기를 줄일 수 있습니다.

예제:

const query = qs.stringify({
  fields: ['title', 'slug', 'createdAt']
});

3. filters (데이터 필터링)

특정 조건을 만족하는 데이터만 가져올 수 있습니다.

특정 값으로 필터링:

const query = qs.stringify({
  filters: {
    category: { name: 'Technology' }
  }
});

연산자(Operators):

연산자설명예시

$eq값이 일치{ title: { $eq: "Hello" } }

$ne값이 다름{ title: { $ne: "Hello" } }

$lt작은 값{ price: { $lt: 100 } }

$lte작거나 같은 값{ price: { $lte: 100 } }

$gt큰 값{ price: { $gt: 100 } }

$gte크거나 같은 값{ price: { $gte: 100 } }

$contains특정 문자열 포함{ title: { $contains: "Hello" } }

4. sort (정렬)

데이터를 정렬할 수 있습니다.

예제:

const query = qs.stringify({
  sort: ['createdAt:desc']
});

???? createdAt 기준으로 내림차순 정렬.

5. pagination (페이징)

데이터를 페이지 단위로 가져오는 기능.

페이지별 데이터 가져오기:

const query = qs.stringify({
  pagination: {
    page: 1,
    pageSize: 10
  }
});

6. publicationState (공개/초안 상태 필터링)

공개된 데이터 또는 초안 데이터를 가져올 수 있습니다.

예제:

const query = qs.stringify({
  publicationState: 'live'
});

7. locale (다국어 지원)

특정 언어의 데이터를 가져올 수 있습니다.

예제:

const query = qs.stringify({
  locale: 'ko'
});

8. populateDeep (모든 관계 데이터 가져오기)

여러 단계의 관계 데이터를 포함하려면 populateDeep을 사용합니다.

예제:

const query = qs.stringify({
  populateDeep: 3
});

3단계까지 관계 데이터를 포함하여 가져오기.

정리

옵션설명

populate관계 데이터 포함

fields특정 필드만 선택

filters데이터 필터링

sort데이터 정렬

pagination페이지 단위로 가져오기

publicationState공개/미리보기 상태 지정

locale특정 언어의 데이터 가져오기

populateDeep모든 관계 데이터 포함

## REST API 파라미터

Strapi의 REST API를 사용할 때, 다양한 쿼리 파라미터를 활용하여 데이터를 필터링, 정렬, 페이지네이션 및 특정 데이터 선택이 가능합니다:

| 파라미터 | 설명 |
| --- | --- |
| `filters` | 특정 조건에 따라 응답 필터링 |
| `locale` | 특정 언어의 콘텐츠 선택 |
| `status` | 초안 및 게시 상태 선택 |
| `populate` | 관련 콘텐츠, 컴포넌트 또는 동적 영역 포함 |
| `fields` | 반환할 특정 필드만 선택 |
| `sort` | 결과 정렬 |
| `pagination` | 페이지 크기 및 번호 제어 |

## 컨트롤러에서 쿼리 파라미터 접근하기

커스텀 컨트롤러에서는 컨텍스트 객체를 통해 쿼리 파라미터에 접근할 수 있습니다:

// 전체 쿼리 객체 접근
ctx.request.query

// 특정 파라미터 접근
ctx.request.query.sort
ctx.request.query.filters
ctx.request.query.populate
ctx.request.query.fields
ctx.request.query.pagination
ctx.request.query.publicationState
ctx.request.query.locale

## 복잡한 쿼리 구성하기

복잡한 쿼리의 경우, Strapi는 수동으로 쿼리 URL을 생성하는 대신 `qs` 라이브러리 사용을 권장합니다. Strapi는 이를 돕기 위한 대화형 쿼리 빌더 도구를 제공합니다:

// 쿼리 파라미터 객체 예시
{
  sort: ['title:asc'],
  filters: {
    title: {
      $eq: 'hello',
    },
  },
  populate: {
    author: {
      fields: ['firstName', 'lastName']
    }
  },
  fields: ['title'],
  pagination: {
    pageSize: 10,
    page: 1,
  },
  status: 'published',
  locale: ['en'],
}

## 요청 정보

컨텍스트 객체를 통해 다른 요청 정보에도 접근할 수 있습니다:

ctx.request.ip       // 요청자의 IP 주소
ctx.request.path     // 요청된 리소스의 경로
ctx.request.method   // HTTP 메소드 (GET, POST 등)
ctx.request.headers  // 요청 헤더