Wagtail Documentation
Wagtail API v2 사용 가이드¶
Wagtail API 모듈은 외부 클라이언트(예: 모바일 앱) 또는 사이트의 프런트엔드에서 사용할 수 있는 공개적이고 읽기 전용이며 JSON 형식의 API를 노출합니다.
이 문서는 Wagtail에서 노출하는 API를 사용하는 개발자를 위한 것입니다. Wagtail 사이트에서 API 모듈을 활성화하는 방법에 대한 문서는 Wagtail API v2 구성 가이드를 참조하십시오.
목차
콘텐츠 가져오기¶
API를 통해 콘텐츠를 가져오려면 다음 엔드포인트 중 하나에 대해 GET 요청을 수행하십시오.
페이지
/api/v2/pages/이미지
/api/v2/images/문서
/api/v2/documents/
참고
사용 가능한 엔드포인트와 해당 URL은 API가 구성된 방식에 따라 사이트마다 다를 수 있습니다.
예제 응답¶
각 응답에는 항목 목록(items)과 총 개수(meta.total_count)가 포함됩니다. 총 개수는 페이지 매김과 무관합니다.
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"
}
]
}
API의 사용자 정의 페이지 필드¶
Wagtail 사이트에는 각각 고유한 필드 집합이 있는 많은 페이지 유형이 포함되어 있습니다. pages 엔드포인트는 기본적으로 공통 필드(예: title 및 slug)만 노출합니다.
API를 사용하여 사용자 정의 페이지 필드에 액세스하려면 ?type 매개변수를 사용하여 페이지 유형을 선택하십시오. 이렇게 하면 결과가 해당 유형의 페이지만 포함하도록 필터링되지만 해당 유형에 대해 내보낸 모든 사용자 정의 필드를 API에서 사용할 수 있게 됩니다.
예를 들어, 구성 문서의 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"
}
]
},
...
]
}
참고
개발자가 명시적으로 내보낸 필드만 API에서 사용할 수 있습니다. 이는 페이지 모델에 api_fields 속성을 추가하여 수행됩니다. 여기에서 구성에 대해 읽을 수 있습니다.
이는 해당 엔드포인트에 노출된 모델이 하나뿐이므로 이미지/문서에는 적용되지 않습니다. 그러나 사용자 정의 이미지/문서 모델이 있는 프로젝트의 경우 api_fields 속성을 사용하여 모든 사용자 정의 필드를 API로 내보낼 수 있습니다.
페이지 매김¶
응답의 항목 수는 ?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이 여기에 나열됩니다.
]
}
참고
?limit 매개변수에 대한 최대값이 있을 수 있습니다. 이는 프로젝트 설정에서 WAGTAILAPI_LIMIT_MAX 를 숫자(새 최대값) 또는 None(최대값 확인 비활성화)으로 설정하여 수정할 수 있습니다.
정렬¶
?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)로 여기에 나열됩니다.
]
}
참고
정렬은 대소문자를 구분하므로 오름차순일 때 소문자는 항상 대문자 뒤에 정렬됩니다.
다중 정렬¶
연속적인 정렬을 위해 ?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": [
페이지가 무작위 순서로 여기에 나열됩니다.
]
}
참고
여러 요청에 걸쳐 일관된 무작위 정렬을 보장할 수 없으므로 무작위로 정렬하는 동안 ?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"
},
]
}
트리 위치로 필터링(페이지만)¶
페이지는 트리의 다른 페이지와의 관계에 따라 추가로 필터링할 수 있습니다.
?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는 요청의 호스트 이름을 기반으로 사이트를 찾습니다. 경우에 따라 다른 사이트에 속한 페이지를 쿼리해야 할 수도 있습니다.
?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
국제화된 사이트를 위한 특수 필터¶
WAGTAIL_I18N_ENABLED 가 True 로 설정되면(자세한 내용은 국제화 활성화 참조) 페이지 엔드포인트에서 두 개의 새로운 필터를 사용할 수 있습니다.
로케일별로 페이지 필터링¶
?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 만 반환합니다.
HTML 경로로 페이지 찾기¶
/api/v2/pages/find/?html_path=<path> 뷰를 사용하여 HTML 경로로 개별 페이지를 찾을 수 있습니다.
이렇게 하면 해당 페이지의 상세 보기로 302 리디렉션 응답 또는 404 찾을 수 없음 응답이 반환됩니다.
예: /api/v2/pages/find/?html_path=/ 는 항상 사이트의 홈페이지로 리디렉션됩니다.
기본 엔드포인트 필드¶
공통 필드¶
이러한 필드는 모든 엔드포인트에서 반환됩니다.
id (숫자)
개체의 고유 ID
참고
페이지 유형을 제외하고 다른 모든 콘텐츠 유형에는 고유한 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매개변수가 추가되었습니다.