1. 개요
2016년 4월 8일에 출시된 Discord의 공식 API이다. Discord 봇, 라이브러리를 이걸로 만들 수 있다. Discord 개발자 독스는 여기에서 볼 수 있다.2022년 10월 23일 기준으로 최신 API 버전은 10이지만 버전 기본값은 6이다. 현재 API 버전 3, 4, 5는 중단되어 이용 불가능하다.
2. Discord HTTP API
JSON 자료 구조를 이용해 요청을 처리하는 REST API로 메시지 생성과 같은 영구적인 요청을 처리하며 Base URL은https://discord.com/api이다. 2.1. API URL
DiscordAPI의 Base URL과 버전 번호를https://discord.com/api/v{버전} 과 같이 조합한다. Base URL만으로 요청을 전송하면 버전 기본값으로 처리된다. 2.2. 인증(Authentication)
따로 명시되지 않은 엔드포인트를 제외하고Authorization 헤더를 넣어야 한다. 그렇지 않으면 401 Unauthorized를 반환한다. Authorization: {토큰유형} {토큰}
토큰의 유형은 Discord 개발자 포털에 의해 발급받은 봇의 토큰인 Bot과 OAuth2 승인으로 발급받은 토큰인 Bearer가 있다. 이러한 토큰은 클라이언트를 식별하는 데 사용된다.
3. Discord Gateway API
웹소켓에 기반한 API. 문자열로 이루어진 JSON 자료 구조 또는 바이너리로 이루어진 ETF로 데이터를 주고받는다. Gateway URL은wss://gateway.discord.gg/이다. Discord에서 이벤트를 수신하고 봇을 온라인 상태로 전환하기 위해 사용된다. 게이트웨이에 연결하면 Hello 이벤트를 수신해 하트비트 간격을 저장해야 한다.
3.1. 게이트웨이에 연결하기
다음 테이블을 참고해 Gateway URL에 연결한다.| Gateway URL 쿼리 문자열 파라미터 테이블 | |
| 필드 | 값 |
| v | 게이트웨이 API 버전 |
| encoding | json 또는 etf |
3.2. Gateway Commands
클라이언트가 웹소켓 서버에 전송할 수 있는 명령이다.3.2.1. 식별(Identify)
봇 클라이언트를 식별하는 데 사용된다. OP 코드는 2.#!syntax json
{
"op": 2,
"d": {
"token": "(토큰)",
"intents": "(인텐트_플래그_값)",
"properties": {
"$os": "(운영_체제)",
"$browser": "(라이브러리_이름)",
"$device": "(라이브러리_이름)"
}
}
}
3.2.2. 재개(Resume)
게이트웨이에 연결했을 때 종종 연결이 끊긴다. 이때 재연결해 게이트웨이 세션을 복원하는데 사용된다. OP 코드는 6.#!syntax json
{
"op": 6,
"d": {
"token": "(토큰)",
"seq": "(마지막으로_수신한_시퀸스_번호)",
"session_id": "(READY_이벤트에서_수신한_세션_ID)"
}
}
3.2.3. 하트비트(Heartbeat)
서버 연결을 유지하는데 사용된다.Hello Gateway Event에서 수신한 하트비트 간격 값을 주기로 계속 전송하지 않으면 연결이 끊긴다. OP 코드는 1. #!syntax json
{
"op": 1,
"d": "(마지막으로_수신한_시퀸스_번호_또는_null)"
}
3.2.4. 프레즌스 업데이트(Update Presence)
클라이언트의 상태 및 활동을 업데이트하는데 사용된다. OP 코드는 3.#!syntax json
{
"op": 3,
"d": {
"since": "(idle_시작한_유닉스_밀리초_시간_또는_null)",
"activities": "(Activity_오브젝트_배열)",
"status": "(클라이언트_상태)",
"afk": "(사용자_afk_여부)"
}
}
3.3. Gateway Events
웹소켓 서버에서 클라이언트에 전송하는 이벤트다.3.3.1. Hello
게이트웨이에 연결하자마자 수신하는 이벤트로 하트비트 간격과 같은 정보를 담고 있다. OP 코드는 10.#!syntax json
{
"op": 10,
"d": {
"heartbeat_interval": "(하트비트_간격_밀리초)"
}
}
3.3.2. Dispatch - Ready
Identify에 성공 시 수신하는 이벤트로 세션 ID와 같은 정보를 담고 있다. OP 코드는 0.#!syntax json
{
"op": 0,
"d": {
"session_id": "(세션_ID)",
"guilds": "(Unavailable_Guild_오브젝트_배열)"
}
}