자주 묻는 질문
개념
헤드리스 CMS가 무엇인가요?
헤드리스 CMS는 콘텐츠를 관리하는 곳과 콘텐츠를 보여 주는 화면을 분리한 콘텐츠 관리 시스템입니다. 여기서 "헤드리스(headless)"는 정해진 화면(UI)이 따로 붙어 있지 않다는 뜻입니다.
전통적인 방식에서는 콘텐츠를 관리하는 곳과 그것을 보여 주는 웹사이트 화면이 하나로 묶여 있습니다. 헤드리스 CMS는 이 둘을 떼어 놓습니다. 콘텐츠는 한곳에서 관리하고, 그 콘텐츠는 약속된 통로(API, 정해진 규칙에 따라 주소로 데이터를 주고받는 방식)로 전달합니다. 그래서 같은 콘텐츠를 웹사이트, 모바일 앱처럼 서로 다른 여러 화면에서 가져다 쓸 수 있습니다.
WEEGLOO가 이 헤드리스 CMS에 해당합니다. 콘텐츠를 콘텐츠 스튜디오에서 만들고 발행하면, 웹사이트나 앱이 그 발행본을 가져와 화면에 보여 줍니다. WEEGLOO의 전체 동작은 어떻게 동작하나에서 다룹니다.
콘텐츠를 어떤 방식으로 제공하나요?
WEEGLOO는 JSON(데이터를 주고받을 때 쓰는 글자 기반의 데이터 형식) 기반의 RESTful API로 콘텐츠를 제공합니다. API는 정해진 규칙에 따라 주소로 데이터를 주고받는 통로입니다.
쓰임에 따라 여러 API가 나뉘어 있습니다.
- 발행된 콘텐츠를 읽어 가는 CDA(Content Delivery API): 웹사이트나 앱이 콘텐츠를 가져와 방문자에게 보여 줄 때 씁니다.
- 콘텐츠를 만들고 관리하는 CMA(Content Management API): 콘텐츠 스튜디오에서 하는 작성·수정·발행 같은 작업을 코드에서 수행할 때 씁니다.
이렇게 읽기와 관리가 나뉘어 있어, 여러 환경에서 필요한 통로만 골라 콘텐츠를 활용할 수 있습니다. 어떤 상황에 어떤 API를 쓰는지는 API 레퍼런스에서 다룹니다.
모바일 앱에서도 쓸 수 있나요?
네. 헤드리스 CMS가 무엇인가요?에서 설명한 것처럼, WEEGLOO는 콘텐츠를 보여 주는 화면과 분리해 콘텐츠를 관리합니다. 그래서 같은 콘텐츠를 웹사이트에서도, 모바일 앱에서도 가져다 쓸 수 있습니다. 발행한 콘텐츠를 앱에서 가져오는 방식은 웹과 같습니다.
회원 로그인을 모바일 앱(Android·iOS)에 붙일 때는 한 가지가 다릅니다. 로그인이 끝난 뒤 그 결과를 앱으로 돌려받는 연결이 웹과 달라, 필요한 기술 단계가 따로 있습니다. 그 단계는 Auth API에서 다룹니다.
모바일 앱을 WEEGLOO와 연동한 완성 예제는 러닝 기록 서비스에서 처음부터 끝까지 볼 수 있습니다.
콘텐츠 관리
여러 언어로 콘텐츠를 배포하려면 어떻게 해야 하나요?
Content나 Media를 여러 언어로 제공하려면, 먼저 Space에 언어(Locale)를 추가합니다.
- 왼쪽 메뉴에서 Space 설정의 Locale 관리 화면으로 이동하세요.
- 오른쪽 위 + 추가 버튼을 누르고, 드롭다운에서 원하는 언어를 고르세요.
- (선택) Fallback Locale을 지정하세요. 그 언어의 값이 비었을 때 대신 보여 줄 언어입니다.
- 저장을 누르세요.
Locale을 추가한 뒤에는, 언어별로 값을 따로 받을 Field마다 다국어를 켜야 합니다. Content Type 편집 화면에서 해당 Field의 Field 상세 설정을 열고, 설정 탭에서 이 Field의 다국어 허용이 켜져 있는지 확인하세요.
자세한 내용은 다국어 관리에서 다룹니다.
Content 유효성 검사는 어떻게 하나요?
유효성 검사는 Field에 "이 칸에 들어올 수 있는 값"의 조건을 거는 기능입니다. 조건에 맞지 않는 값은 저장되지 않아, 잘못된 Content가 쌓이는 것을 막아 줍니다.
걸 수 있는 조건은 Field 종류마다 다릅니다. 예를 들어 Media를 연결하는 Field에는 올릴 수 있는 파일 종류를 제한하거나 파일 크기·이미지 크기를 제한하는 조건이, 숫자 Field에는 값의 범위를 정하는 조건이 있습니다.
Field에 유효성 검사를 더하려면 다음 단계를 진행합니다.
- Content Type 편집 화면으로 가서, 조건을 걸 Field를 누르세요.
- Field 상세 설정에서 유효성 검사 탭으로 이동하세요.
- 그 Field 종류에 쓸 수 있는 조건이 나타납니다. 필요한 조건을 골라 설정하세요.
자세한 내용은 유효성 검사에서 다룹니다.
Content 제목은 어떻게 설정하나요?
Content 제목은 Content 목록에서 각 항목을 알아보는 이름입니다. ShortText 타입의 Field면 어느 것이든 제목으로 쓸 수 있습니다.
Content Type 편집 화면에서 제목으로 쓸 Field를 열고, 그 Field를 제목으로 사용하도록 지정하면 됩니다. 제목은 Content Type마다 한 Field만 가질 수 있어서, 이미 다른 Field가 제목으로 지정돼 있다면 그것을 해제한 뒤에 새로 지정합니다.
처음 Field를 만들 때 제목으로 지정하는 흐름은 Content 모델링에서 다룹니다.
Organization과 Space 관리
사용자를 초대하려면 어떻게 해야 하나요?
어떤 사용자를 Space에 들이려면, 그 사용자가 먼저 Organization에 속해 있어야 합니다. 그래서 협업은 Organization에 초대하는 것에서 시작합니다.
Organization에 사용자를 초대하는 일은 Owner 또는 Admin 역할을 가진 사용자가 할 수 있습니다.
- Organization 설정 화면으로 이동하세요.
- 왼쪽 메뉴에서 Membership을 누르세요.
- 오른쪽 위의 초대 버튼을 누르고, 이메일과 줄 역할 같은 정보를 입력해 초대를 보내세요.
초대받은 사용자는 곧바로 멤버가 됩니다. 따로 "수락" 단계를 거치지 않으며, 초대받은 이메일로 안내 메일이 발송됩니다.
초대와 역할에 대한 자세한 내용은 조직과 스페이스에서 다룹니다.
API
sys.id 값은 고유한 값인가요?
네. sys.id는 서비스 전체에서 고유하게 만들어집니다. 그래서 다른 Organization이나 Space에 속한 리소스와도 값이 겹치지 않습니다.
sys에 담기는 정보는 시스템 속성 (sys)에서 다룹니다.
Content의 참조 리소스는 어떻게 조회하나요?
include 파라미터를 쓰면 한 번의 요청으로 Content와 그것이 가리키는 참조 리소스까지 함께 가져올 수 있습니다.
GET /v1/spaces/{spaceId}/contents?include=1위 요청은 Content 목록을 조회하면서 한 단계 깊이의 연결된 참조 데이터를 함께 가져옵니다. 값을 2나 3으로 올리면 더 깊은 단계까지 펼쳐 가져옵니다.
include는 Content만이 아니라 모든 리소스 조회에서 같은 방식으로 쓸 수 있습니다. 자세한 내용은 공통 쿼리 파라미터에서 다룹니다.
검색 조건에 OR 연산을 지원하나요?
REST API에서 여러 조건을 OR(둘 중 하나라도 맞으면 가져오기)로 묶는 기능은 직접 지원하지 않습니다. 한 요청에 여러 조건을 함께 주면 모두 만족하는(AND) 결과만 나옵니다. OR가 필요하다면 조건별로 요청을 따로 보내고, 받은 결과를 합쳐서 씁니다.
조건으로 목록을 좁히는 방법은 공통 쿼리 파라미터에서 다룹니다.
결제 및 요금
요금제를 변경할 수 있나요?
언제든지 요금제를 올리거나(업그레이드) 내릴(다운그레이드) 수 있습니다. 업그레이드하면 남은 청구 기간에 대해 비례 정산되고, 다운그레이드는 다음 청구 기간부터 적용됩니다.
플랜별 한도와 가격은 요금제에서 다룹니다.
API 사용량은 어떻게 계산되나요?
많은 콘텐츠 플랫폼은 API 호출 횟수(요청 수)로 사용량을 따집니다. WEEGLOO는 호출 횟수가 아니라 실제로 주고받은 데이터 양(데이터 전송량)을 기준으로 사용량을 계산합니다. 같은 횟수의 요청이라도 주고받는 데이터가 크면 사용량이 더 많이 잡힙니다.
Free, Basic, Pro 플랜은 매월 정해진 데이터 전송량을 월 요금 안에 포함합니다. 요금제 표에는 이 전송량을 가늠할 수 있도록 호출 횟수로 환산한 값도 함께 표시됩니다. Advanced Search처럼 검색 한 번이 여러 번의 호출로 계산되는 작업도 이 전송량 안에서 사용됩니다.
정해진 전송량보다 더 큰 사용량이 필요하면 사용한 만큼 청구되는 Enterprise 플랜을 이용할 수 있습니다. 플랜별 데이터 전송 한도는 요금제에서 다룹니다.