서버 소유자를 위한 MineList API

MineList API로 플레이어가 투표했는지 확인하고, 보상을 정확히 한 번만 지급하고, 공개 통계를 읽을 수 있어요. 모든 엔드포인트는 JSON을 반환하며 일반 HTTPS GET 요청을 쓰므로 어떤 언어에서든 사용할 수 있어요.

API 키 받기

서버를 추가하고 소유권을 인증한 다음 소유자 패널을 여세요. API 키는 서버 설정 페이지에 표시돼요. 키는 서버를 식별하므로 비공개로 보관하세요. 유출되면 패널에서 새 키를 만들고 플러그인이나 스크립트를 업데이트하세요.

모든 엔드포인트의 기본 주소는 https://minelist.eu예요.

투표 확인

GET /api/v1/vote?key=API_KEY&username=NICK

플레이어가 오늘 투표했는지, 보상을 이미 수령했는지 알려 줘요.

{"voted":true,"claimed":false,"next_vote_utc":"2026-10-31T00:00:00Z"}

voted는 해당 닉네임이 현재 UTC 날짜에 내 서버에 투표했다면 true예요.
claimed는 그 투표를 이미 수령 처리했다면 true예요.
next_vote_utc는 플레이어가 다시 투표할 수 있는 시각이에요.

투표 수령 처리

GET /api/v1/vote/claim?key=API_KEY&username=NICK

오늘의 투표를 수령 처리해요. 플레이어가 두 번 받지 못하도록 보상을 지급하기 직전에 호출하세요. 가능한 응답은 다음과 같아요.

응답	의미
`{"voted":true,"claimed":true}`	유효한 투표이며 이제 수령 처리됐어요. 보상을 지급하세요.
`{"voted":true,"claimed":false,"already_claimed":true}`	이미 이전에 수령 처리된 투표예요. 아무것도 지급하지 마세요.
`{"voted":false,"claimed":false}`	플레이어가 오늘 투표하지 않았어요.

이번 달 투표 목록

GET /api/v1/votes?key=API_KEY

이번 달에 내 서버가 받은 모든 투표를 반환해요. 월간 투표 순위 보상이나 내 웹사이트의 순위표를 만들 때 유용해요.

공개 서버 통계

GET /api/v1/server/<slug>

이 엔드포인트는 키가 필요 없어요. slug는 MineList 서버 주소의 마지막 부분이에요. 응답 필드 예시는 다음과 같아요.

필드	설명
`name`	서버 이름
`url`	서버 웹사이트
`ip`	접속 주소
`online`	마지막 확인이 성공했는지 여부
`players`	마지막 확인 시점의 접속 플레이어 수
`max_players`	플레이어 슬롯 수
`version`	서버 버전
`votes_month`	이번 달 투표 수
`votes_total`	서버를 추가한 뒤 받은 전체 투표 수
`uptime_30`	최근 30일 가동률(퍼센트)
`rating`	평균 평점
`last_check`	마지막 확인 시각

curl 예제

셸로 나타낸 전체 흐름이에요. Java, PHP, Python, Node.js처럼 HTTP 요청을 보낼 수 있는 언어라면 똑같이 할 수 있어요.

curl -s "https://minelist.eu/api/v1/vote/claim?key=API_KEY&username=Steve"

JSON을 해석해서 claimed가 true이면 보상 명령어를 실행하세요. 예를 들면 give Steve diamond 3처럼요.

NuVotifier 지원

폴링 없이 즉시 보상을 주고 싶다면 MineList가 NuVotifier로 투표를 서버에 보내 드려요. 두 프로토콜 버전을 모두 지원해요. 버전 1은 RSA 공개 키를, 버전 2는 토큰을 사용해요.

서버에 NuVotifier를 설치하고 서버를 재시작하세요.
소유자 패널에 호스트, 포트(기본값 8192), 공개 키(v1) 또는 토큰(v2)을 입력하세요.
테스트 투표 보내기를 누르고 서버 로그에 투표가 기록되는지 확인하세요.

테스트가 실패하면 방화벽에서 Votifier 포트가 열려 있는지, 키를 공백이나 줄바꿈 없이 복사했는지 확인하세요.

실시간 배너

모든 서버에는 현재 상태와 플레이어 수를 보여 주는 468x60 픽셀 실시간 배너가 있어요.

https://minelist.eu/banner/<slug>.png

HTML 삽입 예제예요.

<a href="https://minelist.eu/ko/server/my-server">
  <img src="https://minelist.eu/banner/my-server.png" width="468" height="60" alt="MineList에서 우리 서버에 투표해 주세요">
</a>

권장 사항

페이지를 볼 때마다 API를 호출하지 말고 공개 통계를 최소 1분 동안 캐시하세요.
API 키를 클라이언트 측 코드나 공개 저장소에 절대 넣지 마세요.
수령 처리 엔드포인트는 보상 하나당 한 번만 사용하세요.