(api_v2_usage)=

# Wagtail API v2 사용 가이드

Wagtail API 모듈은 외부 클라이언트(예: 모바일 앱) 또는 사이트의 프런트엔드에서 사용할 수 있는 공개적이고 읽기 전용이며 JSON 형식의 API를 노출합니다.

이 문서는 Wagtail에서 노출하는 API를 사용하는 개발자를 위한 것입니다. Wagtail 사이트에서 API 모듈을 활성화하는 방법에 대한 문서는 [Wagtail API v2 구성 가이드](/advanced_topics/api/v2/configuration)를 참조하십시오.

목차

```{contents}
---
local:
depth: 3
---
```

## 콘텐츠 가져오기

API를 통해 콘텐츠를 가져오려면 다음 엔드포인트 중 하나에 대해 `GET` 요청을 수행하십시오.

-   페이지 `/api/v2/pages/`
-   이미지 `/api/v2/images/`
-   문서 `/api/v2/documents/`

```{note}
사용 가능한 엔드포인트와 해당 URL은 API가 구성된 방식에 따라 사이트마다 다를 수 있습니다.
```

### 예제 응답

각 응답에는 항목 목록(`items`)과 총 개수(`meta.total_count`)가 포함됩니다. 총 개수는 페이지 매김과 무관합니다.

```text
GET /api/v2/endpoint_name/

HTTP 200 OK
Content-Type: application/json

{
    "meta": {
        "total_count": "결과의 총 수"
    },
    "items": [
        {
            "id": 1,
            "meta": {
                "type": "app_name.ModelName",
                "detail_url": "http://api.example.com/api/v2/endpoint_name/1/"
            },
            "field": "value"
        },
        {
            "id": 2,
            "meta": {
                "type": "app_name.ModelName",
                "detail_url": "http://api.example.com/api/v2/endpoint_name/2/"
            },
            "field": "different value"
        }
    ]
}
```

(apiv2_custom_page_fields)=

### API의 사용자 정의 페이지 필드

Wagtail 사이트에는 각각 고유한 필드 집합이 있는 많은 페이지 유형이 포함되어 있습니다. `pages` 엔드포인트는 기본적으로 공통 필드(예: `title` 및 `slug`)만 노출합니다.

API를 사용하여 사용자 정의 페이지 필드에 액세스하려면 `?type` 매개변수를 사용하여 페이지 유형을 선택하십시오. 이렇게 하면 결과가 해당 유형의 페이지만 포함하도록 필터링되지만 해당 유형에 대해 내보낸 모든 사용자 정의 필드를 API에서 사용할 수 있게 됩니다.

예를 들어, [구성 문서](apiv2_page_fields_configuration)의 `blog.BlogPage` 모델에서 `published_date`, `body` 및 `authors` 필드에 액세스하려면:

```
GET /api/v2/pages/?type=blog.BlogPage&fields=published_date,body,authors(name)

HTTP 200 OK
Content-Type: application/json

{
    "meta": {
        "total_count": 10
    },
    "items": [
        {
            "id": 1,
            "meta": {
                "type": "blog.BlogPage",
                "detail_url": "http://api.example.com/api/v2/pages/1/",
                "html_url": "http://www.example.com/blog/my-blog-post/",
                "slug": "my-blog-post",
                "first_published_at": "2016-08-30T16:52:00Z"
            },
            "title": "Test blog post",
            "published_date": "2016-08-30",
            "authors": [
                {
                    "id": 1,
                    "meta": {
                        "type": "blog.BlogPageAuthor",
                    },
                    "name": "Karl Hobley"
                }
            ]
        },

        ...
    ]
}
```

```{note}
개발자가 명시적으로 내보낸 필드만 API에서 사용할 수 있습니다. 이는 페이지 모델에 `api_fields` 속성을 추가하여 수행됩니다. [여기](apiv2_page_fields_configuration)에서 구성에 대해 읽을 수 있습니다.
```

이는 해당 엔드포인트에 노출된 모델이 하나뿐이므로 이미지/문서에는 적용되지 않습니다. 그러나 사용자 정의 이미지/문서 모델이 있는 프로젝트의 경우 `api_fields` 속성을 사용하여 모든 사용자 정의 필드를 API로 내보낼 수 있습니다.

(apiv2_pagination)=

### 페이지 매김

응답의 항목 수는 `?limit` 매개변수(기본값: 20)를 사용하여 변경할 수 있으며 건너뛸 항목 수는 `?offset` 매개변수를 사용하여 변경할 수 있습니다.

예를 들어:

```
GET /api/v2/pages/?offset=20&limit=20

HTTP 200 OK
Content-Type: application/json

{
    "meta": {
        "total_count": 50
    },
    "items": [
        페이지 20 - 40이 여기에 나열됩니다.
    ]
}
```

```{note}
`?limit` 매개변수에 대한 최대값이 있을 수 있습니다. 이는 프로젝트 설정에서 `WAGTAILAPI_LIMIT_MAX` 를 숫자(새 최대값) 또는 `None`(최대값 확인 비활성화)으로 설정하여 수정할 수 있습니다.
```

(api_v2_usage_ordering)=

### 정렬

`?order` 매개변수를 정렬할 필드의 이름으로 설정하여 결과를 모든 필드로 정렬할 수 있습니다.

```
GET /api/v2/pages/?order=title

HTTP 200 OK
Content-Type: application/json

{
    "meta": {
        "total_count": 50
    },
    "items": [
        페이지가 오름차순 제목 순서(a-z)로 여기에 나열됩니다.
    ]
}
```

결과는 기본적으로 오름차순으로 정렬됩니다. 필드 이름 앞에 `-` 기호를 붙여 내림차순으로 변경할 수 있습니다.

```
GET /api/v2/pages/?order=-title

HTTP 200 OK
Content-Type: application/json

{
    "meta": {
        "total_count": 50
    },
    "items": [
        페이지가 내림차순 제목 순서(z-a)로 여기에 나열됩니다.
    ]
}
```

```{note}
정렬은 대소문자를 구분하므로 오름차순일 때 소문자는 항상 대문자 뒤에 정렬됩니다.
```

#### 다중 정렬

연속적인 정렬을 위해 `?order` 에 여러 필드를 전달할 수 있습니다.

```
GET /api/v2/pages/?order=title,-slug

HTTP 200 OK
Content-Type: application/json

{
    "meta": {
        "total_count": 50
    },
    "items": [
        페이지는 제목별로 정렬되고 모든 일치하는 제목(a-z)에 대해 슬러그(z-a)별로 정렬됩니다.
    ]
}
```

#### 무작위 정렬

`?order` 매개변수에 `random` 을 전달하면 결과가 무작위 순서로 반환됩니다. 캐싱이 없으면 각 요청은 다른 순서로 결과를 반환합니다.

```
GET /api/v2/pages/?order=random

HTTP 200 OK
Content-Type: application/json

{
    "meta": {
        "total_count": 50
    },
    "items": [
        페이지가 무작위 순서로 여기에 나열됩니다.
    ]
}
```

```{note}
여러 요청에 걸쳐 일관된 무작위 정렬을 보장할 수 없으므로 무작위로 정렬하는 동안 `?offset` 을 사용할 수 없습니다(따라서 후속 페이지에 대한 요청은 이전 페이지에도 나타난 결과를 반환할 수 있음).
```

### 필터링

모든 필드는 정확한 일치 필터에서 사용할 수 있습니다. 필터 이름을 매개변수로 사용하고 일치시킬 값을 사용하십시오.

예를 들어, 슬러그가 "about"인 페이지를 찾으려면:

```
GET /api/v2/pages/?slug=about

HTTP 200 OK
Content-Type: application/json

{
    "meta": {
        "total_count": 1
    },
    "items": [
        {
            "id": 10,
            "meta": {
                "type": "standard.StandardPage",
                "detail_url": "http://api.example.com/api/v2/pages/10/",
                "html_url": "http://www.example.com/about/",
                "slug": "about",
                "first_published_at": "2016-08-30T16:52:00Z"
            },
            "title": "About"
        },
    ]
}
```

(apiv2_filter_by_tree_position)=

### 트리 위치로 필터링(페이지만)

페이지는 트리의 다른 페이지와의 관계에 따라 추가로 필터링할 수 있습니다.

`?child_of` 필터는 페이지 ID를 사용하고 결과 목록을 해당 페이지의 직접적인 자식만 포함하도록 필터링합니다.

예를 들어, 홈페이지 ID를 필터에 전달하여 주 메뉴를 구성하는 데 유용할 수 있습니다.

```
GET /api/v2/pages/?child_of=2&show_in_menus=true

HTTP 200 OK
Content-Type: application/json

{
    "meta": {
        "total_count": 5
    },
    "items": [
        {
            "id": 3,
            "meta": {
                "type": "blog.BlogIndexPage",
                "detail_url": "http://api.example.com/api/v2/pages/3/",
                "html_url": "http://www.example.com/blog/",
                "slug": "blog",
                "first_published_at": "2016-09-21T13:54:00Z"
            },
            "title": "About"
        },
        {
            "id": 10,
            "meta": {
                "type": "standard.StandardPage",
                "detail_url": "http://api.example.com/api/v2/pages/10/",
                "html_url": "http://www.example.com/about/",
                "slug": "about",
                "first_published_at": "2016-08-30T16:52:00Z"
            },
            "title": "About"
        },

        ...
    ]
}
```

`?ancestor_of` 필터는 페이지 ID를 사용하고 목록을 해당 페이지의 조상(부모, 조부모 등)만 포함하도록 필터링하여 사이트의 루트 페이지까지 내려갑니다.

예를 들어, `type` 필터와 결합하면 `blog.BlogPage` 가 속한 특정 `blog.BlogIndexPage` 를 찾는 데 사용할 수 있습니다. 그 자체로 현재 페이지에서 사이트의 루트 페이지까지 이동 경로를 구성하는 데 사용할 수 있습니다.

`?descendant_of` 필터는 페이지 ID를 사용하고 목록을 해당 페이지의 하위 항목(자식, 손자 등)만 포함하도록 필터링합니다.

(api_filtering_pages_by_site)=

### 사이트별로 페이지 필터링

기본적으로 API는 요청의 호스트 이름을 기반으로 사이트를 찾습니다. 경우에 따라 다른 사이트에 속한 페이지를 쿼리해야 할 수도 있습니다.
`?site=` 필터는 목록을 특정 사이트에 속한 페이지만 포함하도록 필터링하는 데 사용됩니다. 필터에는 사이트의 구성된 호스트 이름이 필요합니다. 동일한 호스트 이름을 사용하지만 다른 포트 번호를 사용하는 여러 사이트가 있는 경우 `hostname:port` 형식을 사용하여 포트 번호로 필터링할 수 있습니다.
예를 들어:

```
GET /api/v2/pages/?site=demo-site.local
GET /api/v2/pages/?site=demo-site.local:8080
```

### 검색

`?search` 매개변수에 쿼리를 전달하면 결과에 대한 전체 텍스트 검색이 수행됩니다.

쿼리는 "용어"(단어 경계 기준)로 분할된 다음 각 용어는 정규화됩니다(소문자 및 악센트 없음).

예: `?search=James+Joyce`

#### 검색 연산자

`search_operator` 는 쿼리의 여러 용어를 처리하는 방법을 지정합니다. 두 가지 가능한 값이 있습니다.

-   `and` - 검색 쿼리의 모든 용어(불용어 제외)는 각 결과에 있어야 합니다.
-   `or` - 검색 쿼리의 하나 이상의 용어가 각 결과에 있어야 합니다.

`or` 연산자는 사용자가 쿼리에 대해 부정확할 수 있고 순위 알고리즘이 관련 없는 결과가 페이지 상단에 반환되지 않도록 하기 때문에 일반적으로 `and` 보다 낫습니다.

기본 검색 연산자는 사이트에서 사용하는 검색 엔진이 순위를 지원하는지 여부에 따라 다릅니다. 지원하는 경우(Elasticsearch) 연산자는 기본적으로 `or` 가 됩니다. 그렇지 않으면(데이터베이스) 기본적으로 `and` 가 됩니다.

같은 이유로 `?search` 를 `?order` 와 함께 사용할 때(순위가 비활성화되므로) `and` 연산자를 사용하는 것도 좋습니다.

예: `?search=James+Joyce&order=-first_published_at&search_operator=and`

(apiv2_i18n_filters)=

### 국제화된 사이트를 위한 특수 필터

`WAGTAIL_I18N_ENABLED` 가 `True` 로 설정되면(자세한 내용은 [](enabling_internationalisation) 참조) 페이지 엔드포인트에서 두 개의 새로운 필터를 사용할 수 있습니다.

#### 로케일별로 페이지 필터링

`?locale=` 필터는 지정된 로케일의 페이지만 포함하도록 목록을 필터링하는 데 사용됩니다. 예를 들어:

```
GET /api/v2/pages/?locale=en-us

HTTP 200 OK
Content-Type: application/json

{
    "meta": {
        "total_count": 5
    },
    "items": [
        {
            "id": 10,
            "meta": {
                "type": "standard.StandardPage",
                "detail_url": "http://api.example.com/api/v2/pages/10/",
                "html_url": "http://www.example.com/usa-page/",
                "slug": "usa-page",
                "first_published_at": "2016-08-30T16:52:00Z",
                "locale": "en-us"
            },
            "title": "American page"
        },

        ...
    ]
}
```

#### 페이지 번역 가져오기

`?translation_of` 필터는 지정된 페이지 ID의 번역인 페이지만 포함하도록 목록을 필터링하는 데 사용됩니다. 예를 들어:

```
GET /api/v2/pages/?translation_of=10

HTTP 200 OK
Content-Type: application/json

{
    "meta": {
        "total_count": 2
    },
    "items": [
        {
            "id": 11,
            "meta": {
                "type": "standard.StandardPage",
                "detail_url": "http://api.example.com/api/v2/pages/11/",
                "html_url": "http://www.example.com/gb-page/",
                "slug": "gb-page",
                "first_published_at": "2016-08-30T16:52:00Z",
                "locale": "en-gb"
            },
            "title": "British page"
        },
        {
            "id": 12,
            "meta": {
                "type": "standard.StandardPage",
                "detail_url": "http://api.example.com/api/v2/pages/12/",
                "html_url": "http://www.example.com/fr-page/",
                "slug": "fr-page",
                "first_published_at": "2016-08-30T16:52:00Z",
                "locale": "fr"
            },
            "title": "French page"
        },
    ]
}
```

### 필드

기본적으로 사용 가능한 필드의 하위 집합만 응답으로 반환됩니다. `?fields` 매개변수를 사용하여 응답에 추가 필드를 추가하고 필요하지 않은 기본 필드를 제거할 수 있습니다.

#### 추가 필드

`?fields` 를 추가하려는 필드 이름의 쉼표로 구분된 목록으로 설정하여 응답에 추가 필드를 추가할 수 있습니다.

예를 들어, `?fields=body,feed_image` 는 `body` 및 `feed_image` 필드를 응답에 추가합니다.

이것은 관계 전반에 걸쳐 사용할 수도 있습니다. 예를 들어, `?fields=body,feed_image(width,height)` 는 응답에 이미지의 `width` 및 `height` 를 중첩합니다.

#### 모든 필드

`?fields` 를 별표(`*`)로 설정하면 사용 가능한 모든 필드가 응답에 추가됩니다. 이는 내보낸 필드를 검색하는 데 유용합니다.

예: `?fields=*`

#### 필드 제거

필요하지 않은 필드는 이름 앞에 `-` 를 붙여 `?fields` 에 추가하여 제거할 수 있습니다.

예를 들어, `?fields=-title,body` 는 `title` 을 제거하고 `body` 를 추가합니다.

이것은 별표와 함께 사용할 수도 있습니다. 예를 들어, `?fields=*,-body` 는 `body` 를 제외한 모든 필드를 추가합니다.

#### 모든 기본 필드 제거

필요한 필드를 정확하게 지정하려면 필드의 첫 번째 항목을 밑줄(`_`)로 설정하여 모든 기본 필드를 제거할 수 있습니다.

예를 들어, `?fields=_,title` 은 제목 필드만 반환합니다.

### 상세 보기

URL 끝에 ID를 추가하여 API에서 단일 개체를 검색할 수 있습니다. 예를 들어:

-   페이지 `/api/v2/pages/1/`
-   이미지 `/api/v2/images/1/`
-   문서 `/api/v2/documents/1/`

내보낸 모든 필드는 기본적으로 응답으로 반환됩니다. `?fields` 매개변수를 사용하여 표시되는 필드를 사용자 정의할 수 있습니다.

예: `/api/v2/pages/1/?fields=_,title,body` 는 ID가 1인 페이지의 `title` 과 `body` 만 반환합니다.

(apiv2_finding_pages_by_path)=

### HTML 경로로 페이지 찾기

`/api/v2/pages/find/?html_path=<path>` 뷰를 사용하여 HTML 경로로 개별 페이지를 찾을 수 있습니다.

이렇게 하면 해당 페이지의 상세 보기로 `302` 리디렉션 응답 또는 `404` 찾을 수 없음 응답이 반환됩니다.

예: `/api/v2/pages/find/?html_path=/` 는 항상 사이트의 홈페이지로 리디렉션됩니다.

## 기본 엔드포인트 필드

### 공통 필드

이러한 필드는 모든 엔드포인트에서 반환됩니다.

**`id` (숫자)**
개체의 고유 ID

```{note}
페이지 유형을 제외하고 다른 모든 콘텐츠 유형에는 고유한 ID 공간이 있으므로 개체에 대한 고유 식별자를 얻으려면 이를 ``type`` 필드와 결합해야 합니다.
```

**`type` (문자열)**
`app_label.ModelName` 형식의 개체 유형

**`detail_url` (문자열)**
개체의 상세 보기 URL

### 페이지

**`title` (문자열)**
**`meta.slug` (문자열)**
**`meta.show_in_menus` (부울)**
**`meta.seo_title` (문자열)**
**`meta.search_description` (문자열)**
**`meta.first_published_at` (날짜/시간)**
이러한 값은 페이지의 해당 필드에서 가져옵니다.

**`meta.html_url` (문자열)**
사이트에 Wagtail에서 생성한 HTML 프런트엔드가 있는 경우 이 필드는 이 페이지의 URL로 설정됩니다.

**`meta.parent`**
부모 페이지에 대한 일부 정보를 중첩합니다(상세 보기에서만 사용 가능).

**`meta.alias_of` (사전)**
페이지가 별칭으로 표시된 경우 원본 페이지 ID와 전체 URL을 반환합니다.

### 이미지

**`title` (문자열)**
이미지 제목 필드의 값입니다. Wagtail 내에서 이 값은 이미지의 `alt` HTML 속성에 사용됩니다.

**`width` (숫자)**
**`height` (숫자)**
원본 이미지 파일의 크기

**`meta.tags` (문자열 목록)**
이미지와 관련된 태그 목록

### 문서

**`title` (문자열)**
문서 제목 필드의 값

**`meta.tags` (문자열 목록)**
문서와 관련된 태그 목록

**`meta.download_url` (문자열)**
문서 파일에 대한 URL

## v1 이후 변경 사항

### 주요 변경 사항

-   목록 응답의 결과 목록 이름이 `items` 로 변경되었습니다(이전에는 `pages`, `images` 또는 `documents` 였음).

### 주요 기능

-   `fields` 매개변수가 필드 제거, 모든 필드 추가 및 중첩 필드 사용자 정의를 허용하도록 개선되었습니다.

### 사소한 기능

-   `html_url`, `slug`, `first_published_at`, `expires_at` 및 `show_in_menus` 필드가 페이지 엔드포인트에 추가되었습니다.
-   `download_url` 필드가 문서 엔드포인트에 추가되었습니다.
-   페이지 엔드포인트의 `type` 매개변수에 여러 페이지 유형을 지정할 수 있습니다.
-   부울 필드를 필터링할 때 `true` 및 `false` 를 사용할 수 있습니다.
-   `order` 를 `search` 와 함께 사용할 수 있습니다.
-   `search_operator` 매개변수가 추가되었습니다.