이 튜토리얼은 Noxyr 서버 API 키를 생성하고, Node.js와 브라우저에서 여섯 개의 엔드포인트를 호출하며, 공개 페이지에 실시간 Discord 데이터를 표시하는 과정을 안내합니다. 봇 연결 없이도 업데이트되는 실제 멤버 카운터를 웹사이트에 달고 싶었다면, 바로 이 방법이 그것입니다.

A key is generated, a curl request is sent, and the JSON response renders as live text on a page. 1 nxr_••••••••• 2 curl /api/v1/server 3 { memberCount: 812 } 812 members online

1단계: 키 생성하기

Noxyr 대시보드를 열고 서버를 선택한 뒤 API Access로 이동하세요. Generate API Key를 클릭합니다. 키(nxr_로 시작)는 한 번만 표시되므로, 지금 바로 환경 변수에 복사해 두세요. 서버에는 SHA-256 해시만 저장되므로, 키를 잃어버리면 다시 생성해야 합니다.

2단계: 권한 범위 설정하기

키 아래에 있는 여섯 개의 토글이 키가 읽을 수 있는 항목을 결정합니다. 서버 개요, 티켓, 활동, 인보이스, 리뷰, 이벤트입니다. 필요 없는 항목은 끄세요. 비활성화된 범위는 즉시 403을 반환하므로, 키가 유출되더라도 활성화하지 않은 범위는 읽을 수 없습니다.

3단계: curl로 간단히 테스트하기

curl https://noxyrbot.com/api/v1/server \
  -H "Authorization: Bearer nxr_YOUR_KEY"

서버의 id, 이름, 아이콘 URL, 멤버 수, 온라인 수, 부스트가 담긴 JSON이 보여야 합니다.

4단계: Node.js에서 호출하기

const KEY = process.env.NOXYR_API_KEY;

async function getStats() {
    const [server, tickets, activity] = await Promise.all([
        fetch('https://noxyrbot.com/api/v1/server',              { headers: { Authorization: `Bearer ${KEY}` } }),
        fetch('https://noxyrbot.com/api/v1/tickets',             { headers: { Authorization: `Bearer ${KEY}` } }),
        fetch('https://noxyrbot.com/api/v1/activity?days=7',     { headers: { Authorization: `Bearer ${KEY}` } })
    ]);
    return {
        server:   await server.json(),
        tickets:  await tickets.json(),
        activity: await activity.json()
    };
}

getStats().then(console.log);

5단계: 브라우저에서 호출하기

CORS가 열려 있으므로 정적 사이트에서 바로 fetch할 수 있습니다. 실제 사용자에게 배포되는 클라이언트 코드에 키를 넣지 마세요. 개발자 도구를 여는 누구나 키를 볼 수 있습니다. 안전한 방법은 두 가지입니다.

  • 프록시 뒤의 공개 대시보드: 직접 운영하는 작은 서버리스 함수가 환경 변수에서 키를 읽고, Noxyr를 호출한 뒤 JSON을 브라우저로 전달합니다.
  • 신뢰할 수 있는 내부 도구: 페이지를 자체 인증 뒤에 두고, 그다음에 키를 넣으세요.
// Cloudflare Worker / Vercel Edge - key stays on the server
export default {
    async fetch(request, env) {
        const upstream = await fetch('https://noxyrbot.com/api/v1/server', {
            headers: { Authorization: `Bearer ${env.NOXYR_API_KEY}` }
        });
        return new Response(await upstream.text(), {
            headers: { 'content-type': 'application/json', 'cache-control': 'public, max-age=60' }
        });
    }
};

6단계: 화면에 표시하기

<div id="members">…</div>
<script>
    fetch('/api/live-server-stats')
        .then((r) => r.json())
        .then((data) => {
            document.getElementById('members').textContent =
                `${data.memberCount.toLocaleString()} members · ${data.onlineCount} online`;
        });
</script>

요청 제한과 캐싱

키당 분당 60회 요청으로 제한됩니다. 비공개 대시보드에서는 실시간 갱신이 좋지만, 공개 사이트에서는 낭비입니다. 프록시 계층에서 업스트림 응답을 30~60초 동안 캐시하면 제한에 가까이 갈 일이 없습니다.

오류 응답

  • 401 unauthorized: 키가 없거나 잘못되었습니다.
  • 403 key_disabled: 대시보드에서 키가 꺼져 있습니다.
  • 403 scope_disabled: 해당 엔드포인트의 권한 범위가 꺼져 있습니다. 대시보드에서 켜세요.
  • 404 guild_unavailable: 봇이 해당 서버에서 제거되었습니다.
  • 429 rate_limited: 요청 속도를 줄이세요.

API가 이런 구조인 이유가 궁금하다면 Discord 봇을 위한 API 설계 원칙을 읽어 보세요.