마인플랫폼 문서

테마

예제 모음 ​

처음이라면

먼저 초보자용 따라하기를 보세요.
이 페이지는 조금 더 정리된·재사용하기 좋은 코드를 모아 둔 곳이에요.

변수 이름은 영어, 주석과 로그만 한국어예요.
키는 코드에 직접 넣지 말고, 가능하면 환경 변수로 넣으세요.

bash
# Mac / Linux
export MP_API_KEY="mp_live_여기에_본인_키"

# Windows PowerShell
$env:MP_API_KEY = "mp_live_여기에_본인_키"

1. curl — 살아 있는지 + 목록 ​

bash
# API 서버가 켜져 있는지 확인 (키 필요 없음)
curl -sS "https://api.mineplatform.kr/health"

# 내 서버 목록 (키 필요)
curl -sS \
  -H "Authorization: Bearer ${MP_API_KEY}" \
  -H "Accept: application/json" \
  "https://api.mineplatform.kr/v1/servers"

2. JavaScript — 간결 + 한국어 주석·로그 ​

Node.js 18 이상 권장 (fetch 내장).

js
/**
 * 마인플랫폼 공개 API — 서버 목록 조회 예제
 * 실행: node list-servers.js
 */

const baseUrl = "https://api.mineplatform.kr";
const apiKey = process.env.MP_API_KEY;

if (!apiKey) {
  console.error("오류: 환경 변수 MP_API_KEY 가 없어요.");
  console.error("예) export MP_API_KEY=\"mp_live_…\"");
  process.exit(1);
}

async function listServers() {
  console.log("[정보] 서버 목록을 요청합니다…");

  const res = await fetch(`${baseUrl}/v1/servers`, {
    method: "GET",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      Accept: "application/json",
    },
  });

  // 너무 자주 부르면 잠시 막혀요 (초당 1회)
  if (res.status === 429) {
    const retryAfter = Number(res.headers.get("Retry-After") || "1");
    console.warn(`[경고] 요청이 너무 빨라요. ${retryAfter}초 뒤에 다시 시도하세요.`);
    process.exit(1);
  }

  const body = await res.json().catch(() => ({}));

  if (!res.ok) {
    console.error("[오류] 요청 실패 · HTTP", res.status);
    console.error("[오류] 메시지:", body.error || "(없음)");
    process.exit(1);
  }

  const servers = Array.isArray(body.servers) ? body.servers : [];
  console.log(`[완료] ${servers.length}개의 서버를 가져왔어요.`);

  for (const server of servers) {
    console.log(
      `  · ${server.name} | ${server.address} | ${server.status} | ${server.edition}`,
    );
  }

  return servers;
}

listServers().catch((err) => {
  console.error("[오류] 예상치 못한 문제:", err.message || err);
  process.exit(1);
});

3. JavaScript — 함수만 짧게 ​

다른 코드에 붙일 때 쓰기 좋은 최소 버전이에요.

js
// 키는 환경 변수에서 읽어요
const apiKey = process.env.MP_API_KEY;

/** 내 개인 서버 배열을 반환해요. 실패하면 에러를 던져요. */
export async function getMyServers() {
  const res = await fetch("https://api.mineplatform.kr/v1/servers", {
    headers: { Authorization: `Bearer ${apiKey}` },
  });
  const data = await res.json();
  if (!res.ok) throw new Error(data.error || `HTTP ${res.status}`);
  return data.servers;
}

// 사용 예
getMyServers()
  .then((servers) => console.log("서버 개수:", servers.length))
  .catch((err) => console.error("실패:", err.message));

4. Python — 간결 + 한국어 주석·로그 ​

python
"""
마인플랫폼 공개 API — 서버 목록 조회 예제
실행: python list_servers.py
"""

import json
import os
import sys
import urllib.error
import urllib.request

base_url = "https://api.mineplatform.kr"
api_key = os.environ.get("MP_API_KEY")

if not api_key:
    print("오류: 환경 변수 MP_API_KEY 가 없어요.", file=sys.stderr)
    print('예) export MP_API_KEY="mp_live_…"', file=sys.stderr)
    sys.exit(1)


def list_servers():
    print("[정보] 서버 목록을 요청합니다…")

    req = urllib.request.Request(
        f"{base_url}/v1/servers",
        headers={
            "Authorization": f"Bearer {api_key}",
            "Accept": "application/json",
        },
        method="GET",
    )

    try:
        with urllib.request.urlopen(req, timeout=15) as res:
            body = json.load(res)
    except urllib.error.HTTPError as err:
        raw = err.read().decode("utf-8", errors="replace")
        if err.code == 429:
            wait = err.headers.get("Retry-After", "1")
            print(f"[경고] 요청이 너무 빨라요. {wait}초 뒤에 다시 시도하세요.")
        elif err.code == 401:
            print("[오류] API 키가 잘못됐거나 삭제된 키예요.")
        else:
            print(f"[오류] 요청 실패 · HTTP {err.code}")
            print("[오류] 응답:", raw)
        sys.exit(1)

    servers = body.get("servers") or []
    print(f"[완료] {len(servers)}개의 서버를 가져왔어요.")

    for server in servers:
        print(
            f"  · {server.get('name')} | {server.get('address')} | "
            f"{server.get('status')} | {server.get('edition')}"
        )

    return servers


if __name__ == "__main__":
    list_servers()

5. PowerShell — 한국어 로그 ​

powershell
# 마인플랫폼 공개 API — 서버 목록 예제

$baseUrl = "https://api.mineplatform.kr"
$apiKey = $env:MP_API_KEY

if (-not $apiKey) {
  Write-Host "오류: 환경 변수 MP_API_KEY 가 없어요." -ForegroundColor Red
  Write-Host '예) $env:MP_API_KEY = "mp_live_…"'
  exit 1
}

Write-Host "[정보] 서버 목록을 요청합니다…"

try {
  $body = Invoke-RestMethod -Uri "$baseUrl/v1/servers" -Headers @{
    Authorization = "Bearer $apiKey"
    Accept        = "application/json"
  }

  $servers = @($body.servers)
  Write-Host "[완료] $($servers.Count)개의 서버를 가져왔어요."

  foreach ($server in $servers) {
    Write-Host ("  · {0} | {1} | {2} | {3}" -f $server.name, $server.address, $server.status, $server.edition)
  }
}
catch {
  Write-Host "[오류] 요청에 실패했어요:" $_.Exception.Message -ForegroundColor Red
  exit 1
}

6. 2초마다 한 번씩 (폴링) ​

초당 1회 제한보다 여유 있게 돌리세요.

js
// 2초마다 서버 목록을 확인해요 (초보용 폴링)

const apiKey = process.env.MP_API_KEY;
const intervalMs = 2000; // 2초

async function tick() {
  try {
    const res = await fetch("https://api.mineplatform.kr/v1/servers", {
      headers: { Authorization: `Bearer ${apiKey}` },
    });

    if (res.status === 429) {
      console.log("[경고] 속도 제한에 걸렸어요. 이번 회차는 건너뜁니다.");
      return;
    }

    const { servers = [] } = await res.json();
    console.log(
      `[정보] ${new Date().toLocaleTimeString("ko-KR")} · 서버 ${servers.length}개`,
    );
  } catch (err) {
    console.error("[오류] 네트워크 문제:", err.message);
  }
}

console.log("[정보] 2초 간격으로 조회를 시작합니다. 끝내려면 Ctrl+C");
tick();
setInterval(tick, intervalMs);

7. 잘못된 호출 확인 ​

bash
# 키 없이 → 401 예상
curl -i "https://api.mineplatform.kr/v1/servers"

# 잘못된 주소 → 404 예상
curl -i -H "Authorization: Bearer ${MP_API_KEY}" \
  "https://api.mineplatform.kr/v1/server"

다음 읽을 문서 ​