마인플랫폼 문서

테마

초보자용 따라하기 ​

코딩을 처음 해 보는 분도 복사 → 붙여넣기만으로 API를 호출해 볼 수 있게 준비했어요.

준비물

  1. 대시보드 → API에서 발급한 키 (mp_live_ 로 시작)
  2. 컴퓨터에 Node.js(자바스크립트) 또는 Python 3 중 하나

키는 절대 카톡·디스코드에 올리지 마세요. 아래에 보이는 mp_live_여기에_본인_키 부분만 본인 키로 바꾸면 돼요.

변수 이름은 영어로 두고, 주석과 로그 메시지만 한국어로 적어 두었어요.

1분 테스트 (터미널 / curl) ​

가장 짧은 방법이에요. Windows면 PowerShell, Mac이면 터미널을 여세요.

bash
# 1) API가 살아 있는지 확인 (키 필요 없음)
curl https://api.mineplatform.kr/health

# 2) 내 서버 목록 가져오기 (키 필요)
#    ↓ mp_live_ 뒤를 본인 키로 바꾸세요
curl -H "Authorization: Bearer mp_live_여기에_본인_키" https://api.mineplatform.kr/v1/servers

성공하면 화면에 {"servers":[...]} 같은 글자가 나와요.
서버를 아직 안 등록했다면 "servers":[] (빈 목록)도 정상이에요.

자바스크립트 — 아주 짧은 버전 ​

파일 이름 예: servers.js

js
// 마인플랫폼 API로 내 서버 목록을 가져오는 초간단 예제예요.

const apiKey = "mp_live_여기에_본인_키"; // ← 본인 키로 바꾸세요
const url = "https://api.mineplatform.kr/v1/servers";

async function listServers() {
  console.log("서버 목록을 요청하는 중…");

  const res = await fetch(url, {
    headers: {
      // 인증: Bearer + 공백 + API 키
      Authorization: "Bearer " + apiKey,
    },
  });

  // 초당 1번만 호출할 수 있어요. 너무 자주 부르면 429가 나요.
  if (res.status === 429) {
    console.log("너무 빨리 요청했어요. 1초 뒤에 다시 시도해 주세요.");
    return;
  }

  if (!res.ok) {
    console.log("요청에 실패했어요. 상태 코드:", res.status);
    const errBody = await res.json().catch(() => ({}));
    console.log("서버 메시지:", errBody.error || "(없음)");
    return;
  }

  const data = await res.json();
  const servers = data.servers || [];

  console.log("총 " + servers.length + "개의 서버를 찾았어요.");

  for (const server of servers) {
    console.log(
      "- " + server.name + " / " + server.address + " (" + server.status + ")",
    );
  }
}

listServers();

실행:

bash
node servers.js

예상 로그:

서버 목록을 요청하는 중…
총 1개의 서버를 찾았어요.
- 블록마을 / play.example.com:25565 (published)

파이썬 — 아주 짧은 버전 ​

파일 이름 예: servers.py
(추가 패키지 설치 없이, 파이썬만 있으면 돼요.)

python
# 마인플랫폼 API로 내 서버 목록을 가져오는 초간단 예제예요.

import json
import urllib.request

api_key = "mp_live_여기에_본인_키"  # ← 본인 키로 바꾸세요
url = "https://api.mineplatform.kr/v1/servers"

print("서버 목록을 요청하는 중…")

req = urllib.request.Request(
    url,
    headers={"Authorization": "Bearer " + api_key},
)

try:
    with urllib.request.urlopen(req, timeout=15) as res:
        data = json.load(res)
except urllib.error.HTTPError as err:
    if err.code == 429:
        print("너무 빨리 요청했어요. 1초 뒤에 다시 시도해 주세요.")
    elif err.code == 401:
        print("API 키가 잘못됐거나 삭제된 키예요. 대시보드에서 다시 확인해 주세요.")
    else:
        print("요청에 실패했어요. 상태 코드:", err.code)
    raise SystemExit(1)

servers = data.get("servers", [])
print("총", len(servers), "개의 서버를 찾았어요.")

for server in servers:
    print("-", server["name"], "/", server["address"], "(" + server["status"] + ")")

실행:

bash
python servers.py

PowerShell — Windows 초간단 버전 ​

powershell
# 마인플랫폼 API 초간단 예제 (PowerShell)

$apiKey = "mp_live_여기에_본인_키"  # ← 본인 키로 바꾸세요

Write-Host "서버 목록을 요청하는 중…"

try {
  $result = Invoke-RestMethod `
    -Uri "https://api.mineplatform.kr/v1/servers" `
    -Headers @{ Authorization = "Bearer $apiKey" }

  $servers = $result.servers
  Write-Host ("총 {0}개의 서버를 찾았어요." -f $servers.Count)

  foreach ($server in $servers) {
    Write-Host ("- {0} / {1} ({2})" -f $server.name, $server.address, $server.status)
  }
}
catch {
  Write-Host "요청에 실패했어요:" $_.Exception.Message
}

자주 나오는 메시지 ​

로그 / 상황뜻해결
총 0개의 서버를 찾았어요.키는 맞는데 개인 서버가 없음웹에서 서버를 먼저 등록해요
API 키가 잘못됐거나… / 401키 오타·폐기대시보드에서 새 키 발급
너무 빨리 요청했어요 / 4291초에 2번 이상 호출1~2초 쉬고 다시
아무 글자도 안 나옴파일/실행 위치를 잘못 봄node servers.js 한 폴더에서 실행

더 많은 예시는 예제 모음을,
필드 설명은 서버 목록 API를 보시면 돼요.