[[분류:Discord]]
[include(틀:Discord)]
[목차]

== 개요 ==
2016년 4월 8일에 출시된 '''[[Discord]]의 공식 API'''이다. Discord 봇, 라이브러리를 이걸로 만들 수 있다. Discord 개발자 독스는 [[https://discord.com/developers/docs/intro|여기에서]] 볼 수 있다. 

2022년 10월 23일 기준으로 최신 API 버전은 10이지만 버전 기본값은 6이다. 현재 API 버전 3, 4, 5는 중단되어 이용 불가능하다. 

== Discord HTTP API ==
[[JSON]] 자료 구조를 이용해 요청을 처리하는 [[REST]] [[API]]로 메시지 생성과 같은 영구적인 요청을 처리하며 Base URL은 {{{https://discord.com/api}}}이다. 

=== API URL ===
DiscordAPI의 Base URL과 버전 번호를 {{{https://discord.com/api/v{버전} }}}과 같이 조합한다. Base URL만으로 요청을 전송하면 버전 기본값으로 처리된다. 

=== 인증(Authentication) ===
따로 명시되지 않은 엔드포인트를 제외하고 {{{Authorization}}} 헤더를 넣어야 한다. 그렇지 않으면 {{{401 Unauthorized}}}를 반환한다. 
{{{Authorization: {토큰유형} {토큰}
}}}

토큰의 유형은 Discord 개발자 포털에 의해 발급받은 봇의 토큰인 '''Bot'''과 [[OAuth|OAuth2]] 승인으로 발급받은 토큰인 '''Bearer'''가 있다. 이러한 토큰은 클라이언트를 식별하는 데 사용된다. 

== Discord Gateway API ==
[[웹소켓]]에 기반한 API. 문자열로 이루어진 JSON 자료 구조 또는 [[바이너리]]로 이루어진 ETF로 데이터를 주고받는다. Gateway URL은 {{{wss://gateway.discord.gg/}}}이다. Discord에서 이벤트를 수신하고 봇을 온라인 상태로 전환하기 위해 사용된다. 

게이트웨이에 연결하면 Hello 이벤트를 수신해 하트비트 간격을 저장해야 한다. 

=== 게이트웨이에 연결하기 ===
다음 테이블을 참고해 Gateway URL에 연결한다. 
|||| '''Gateway URL 쿼리 문자열 파라미터 테이블''' ||||
|| 필드 || 값 ||
|| v || 게이트웨이 API 버전 ||
|| encoding || {{{json}}} 또는 {{{etf}}} ||

=== Gateway Commands ===
클라이언트가 웹소켓 서버에 전송할 수 있는 명령이다. 

==== 식별(Identify) ====
'''봇 클라이언트를 식별'''하는 데 사용된다. OP 코드는 2.
{{{#!syntax json
{
    "op": 2,
    "d": {
        "token": "(토큰)",
        "intents": "(인텐트_플래그_값)",
        "properties": {
            "$os": "(운영_체제)",
            "$browser": "(라이브러리_이름)",
            "$device": "(라이브러리_이름)"
        }
    }
}
}}}

==== 재개(Resume) ====
게이트웨이에 연결했을 때 종종 연결이 끊긴다. 이때 '''재연결해 게이트웨이 세션을 복원'''하는데 사용된다. OP 코드는 6. 
{{{#!syntax json
{
    "op": 6,
    "d": {
        "token": "(토큰)",
        "seq": "(마지막으로_수신한_시퀸스_번호)",
        "session_id": "(READY_이벤트에서_수신한_세션_ID)"
    }
}
}}}

==== 하트비트(Heartbeat) ====
'''서버 연결을 유지'''하는데 사용된다. {{{Hello}}} Gateway Event에서 수신한 하트비트 간격 값을 주기로 계속 전송하지 않으면 연결이 끊긴다. OP 코드는 1. 
{{{#!syntax json
{
    "op": 1,
    "d": "(마지막으로_수신한_시퀸스_번호_또는_null)"
}
}}}

==== 프레즌스 업데이트(Update Presence) ====
'''클라이언트의 상태 및 활동을 업데이트'''하는데 사용된다. OP 코드는 3.
{{{#!syntax json
{
    "op": 3,
    "d": {
        "since": "(idle_시작한_유닉스_밀리초_시간_또는_null)",
        "activities": "(Activity_오브젝트_배열)",
        "status": "(클라이언트_상태)",
        "afk": "(사용자_afk_여부)"
    }
}
}}}

=== Gateway Events ===
웹소켓 서버에서 클라이언트에 전송하는 이벤트다. 

==== Hello ====
'''게이트웨이에 연결하자마자 수신하는 이벤트'''로 하트비트 간격과 같은 정보를 담고 있다. OP 코드는 10.
{{{#!syntax json
{
    "op": 10,
    "d": {
        "heartbeat_interval": "(하트비트_간격_밀리초)"
    }
}
}}}

==== Dispatch - Ready ====
'''Identify에 성공 시 수신하는 이벤트'''로 세션 ID와 같은 정보를 담고 있다. OP 코드는 0.
{{{#!syntax json
{
    "op": 0,
    "d": {
        "session_id": "(세션_ID)",
        "guilds": "(Unavailable_Guild_오브젝트_배열)"
    }
}
}}}

== 기타 ==
=== 데이터 암호화 ===
HTTP API와 웹소켓 API 둘 다 [[TLS]] 1.2를 이용 중이다. 

=== 스노우플레이크 ===
[[Twitter]]의 [[https://github.com/twitter/snowflake/tree/snowflake-2010|스노우플레이크]] 포맷을 활용 중이다. 이러한 스노우플레이크 ID는 자식 오브젝트가 부모 오브젝트의 ID와 동일한 것을 제외하고 서로 겹치지 않으며 JSON 자료 구조에서는 문자열로 반환된다.