사이드 메뉴
시작하기
로그인
커뮤니케이션
광고
표기 안내
이 문서는 카카오디벨로퍼스 문서에서 사용하는 표기 규칙을 안내합니다. REST API 레퍼런스 문서의 파라미터와 필드 표를 확인할 때 참고할 수 있습니다. 문서에서 사용하는 용어의 뜻은 용어집을 참고합니다.
| 표기 | 의미 |
|---|---|
access_token | 코드 서체는 파라미터와 필드 이름, 값, 코드 조각을 나타냅니다. |
${ACCESS_TOKEN} | 달러 기호와 중괄호로 감싼 대문자 표기는 실제 값으로 교체해야 하는 자리 표시자입니다. 예제 요청에 주로 사용합니다. |
yyyy-MM-dd'T'HH:mm:ss | 날짜와 시간 값은 형식 문자열로 안내합니다. |
(예: login,message) | 괄호 안의 예 표기는 실제 사용 예시를 나타냅니다. |
| 표기 | 의미 |
|---|---|
| [앱] > [플랫폼 키] | 대괄호는 메뉴, 버튼, 설정 항목 명칭을 나타냅니다. 부등호로 이어진 대괄호는 순서대로 이동하는 메뉴 경로를 나타냅니다. |
개발 문서의 각 API와 기능 설명은 기본 정보 표로 시작합니다. 기본 정보 표는 API의 사양과 기초 정보, 사용을 위한 선행 작업을 요약한 표로, 호출 전에 확인해야 할 내용을 안내합니다. 구성 항목은 문서 유형에 따라 다릅니다.
| 항목 | 의미 |
|---|---|
| 메서드, URL | API 요청에 사용하는 HTTP 메서드와 요청 URL입니다. |
| 인증 방식 | 요청에 사용할 수 있는 인증 방식입니다. 인증 방식에 따라 요청 규격이 다른 경우 각각 안내합니다. |
| 요구 사항 | API를 사용하기 위해 필요한 선행 작업입니다. 각 항목의 링크에서 설정 방법을 확인할 수 있습니다. |
| 참고 | 필요한 참고 정보를 제공하는 관련 문서입니다. |
| 항목 | 의미 |
|---|---|
| 레퍼런스 | 기능 구현에 사용하는 SDK의 함수와 클래스입니다. 링크에서 SDK 레퍼런스를 확인할 수 있습니다. |
| 앱 설정 | 기능을 사용하기 전에 필요한 설치, 초기화 등 설정 작업입니다. 각 항목의 링크에서 방법을 확인할 수 있습니다. |
요구 사항과 참고 항목은 REST API 문서와 동일합니다.
요청의 구성 요소는 파라미터, 응답의 구성 요소는 필드로 지칭합니다. 두 구성 요소 모두 이름, 타입, 설명 열을 가진 표로 안내합니다. 요청 파라미터 표에는 필수 열을 함께 안내하고, 응답 필드 표에는 필요한 경우에만 필수 열을 둡니다.
| 표기 | 의미 |
|---|---|
O | 반드시 전달해야 하는 파라미터입니다. 응답 표에서는 항상 포함되는 필드를 뜻합니다. |
X | 생략할 수 있는 파라미터입니다. 기본값이 있는 경우 설명에 함께 안내합니다. |
X* | 조건에 따라 전달하는 파라미터입니다. 조건은 표 바로 아래 각주에서 안내하며, 같은 별표가 붙은 파라미터들이 하나의 택일 또는 조합 관계를 이룹니다. 별표가 여러 종류인 경우 각주와 별표 개수로 대응 관계를 구분합니다. |
설명 열은 파라미터나 필드의 정의를 먼저 안내하고, 사용 목적과 조건, 부가 정보는 다음 줄에 안내합니다. 굵은 라벨은 다음 정보를 구분합니다.
| 표기 | 의미 |
|---|---|
| 제공 조건 | 응답에 조건부로 포함되는 필드의 포함 조건 |
| 중요 | 다른 파라미터 값에 따라 달라지는 필수 조건과 같이 요청 전 반드시 확인해야 하는 내용 |
| 사용 가능한 값 | 파라미터에 사용할 수 있는 값의 목록 |
| 참고 | 함께 알아두면 좋은 부가 정보 |
| 주의 | 잘못 사용하기 쉬운 부분에 대한 유의 사항 |
타입 열은 값의 직렬화 타입 또는 참조할 정의 표를 안내합니다.
| 표기 | 의미 |
|---|---|
String, Integer, Long, Double, Boolean | 기본 타입입니다. 숫자와 불리언 타입은 허용 값이 제한되어 있어도 기본 타입으로 표기하고, 허용 값은 설명에서 안내합니다. |
Datetime | 날짜와 시간 값입니다. 값의 형식은 설명에서 형식 문자열로 안내합니다. |
JSON | 키와 값의 쌍으로 구성된 객체입니다. 구성 항목이 정해져 있으면 별도 표로 안내합니다. |
Multipart File | 멀티파트 폼 데이터로 전달하는 파일입니다. |
String[] | 배열 타입은 요소 타입 뒤에 대괄호를 붙여 표기합니다. 객체와 정의 표가 있는 열거형의 배열도 같은 형태로 표기합니다(예: Location[], Enum: DeviceType[]). |
Campaign | 링크 표기는 객체 타입입니다. 링크를 통해 해당 객체의 속성 표를 확인할 수 있습니다. |
허용 값이 정해진 문자열 집합인 파라미터는 열거형으로 표기합니다.
| 표기 | 의미 |
|---|---|
Enum | 열거형 파라미터입니다. 허용 값과 값별 의미는 설명에서 목록으로 안내합니다. |
Enum: Color | 별도 정의 표가 있는 열거형입니다. 타입 열의 링크는 타입 자체의 정의를 가리키며, 전체 허용 값과 값별 의미는 링크된 정의 표에서 확인합니다. 설명에 값 목록이 함께 있는 경우, 해당 API에서 설정하거나 응답으로 받을 수 있는 값은 그중 목록에 있는 값입니다. |
열거형 정의 표의 제목은 Enum: 이름 형식으로 표기하고, 필요한 경우 괄호로 구분 정보를 덧붙입니다(예: Enum: Status (캠페인)). 정의 표는 값과 설명 두 열로 구성하고, 값 열은 코드 서체 없이 표기합니다. 값의 의미가 특정 속성 하나로 표현되는 경우에는 설명 대신 그 속성 이름을 열 제목으로 사용합니다(예: Enum: Color의 16진수 색상 코드).
| 표기 | 의미 |
|---|---|
| (기본값) | 값 목록에서 해당 값이 생략 시 적용되는 기본값임을 나타냅니다. |
(기본값: BLUE) | 파라미터 생략 시 적용되는 기본값을 나타냅니다. |
| (최대: 50자) | 값이 넘을 수 없는 최대 길이 또는 최대 크기를 나타냅니다. |
(최소: 1, 최대: 45, 기본값: 1) | 허용 범위와 기본값을 함께 나타냅니다. |
PUBLIC으로 고정 | 값이 하나로 정해져 있어 다른 값을 사용할 수 없음을 나타냅니다. 응답 표에서는 항상 같은 값이 반환되는 필드를 뜻합니다. |
| 1~50 사이의 값 | 물결표는 이상, 이하의 연속 범위를 나타냅니다. |
| (단위: 초) | 수치형 파라미터가 사용하는 단위를 나타냅니다. |
| 640x640 픽셀 | 이미지 치수는 가로x세로 형태로 표기하고 단위를 뒤에 붙입니다. |
Android, iOS, JavaScript, Flutter SDK 문서의 파라미터 표는 타입을 각 프로그래밍 언어의 실제 타입으로 표기합니다(예: Kotlin List<String>, Swift [String]). 열거형과 객체도 SDK에 정의된 클래스 타입으로 표기하며, 상세 규격은 각 SDK 레퍼런스에서 확인할 수 있습니다.
이외의 표기 규칙은 REST API 문서와 동일하게 적용됩니다.