GET /v1/servers

로그인한 사용자가 개인으로 등록한 마인크래프트 서버 목록을 반환해요.
조직(organization_id가 있는) 서버는 포함되지 않아요.

요청

GET /v1/servers HTTP/1.1
Host: api.mineplatform.kr
Authorization: Bearer mp_live_YOUR_KEY
Accept: application/json

항목	값
Method	GET
Path	/v1/servers
Auth	Bearer API 키 필수
Query	현재 없음 (필터·페이지네이션 미지원)
Body	없음

스코프 (무엇이 나오나)

다음을 모두 만족하는 서버만 반환해요.

1. created_by = API 키 소유자 (user_id)
2. organization_id IS NULL (개인 등록)
3. 상태·에디션과 관계없이 DB에 있는 행 (draft/published 등 status 필드 그대로 포함)

정렬: updated_at 내림차순
최대 개수: 100 (그 이상이면 최근 수정분 100개만)

조직 서버가 안 보여요

조직 대시보드에서 등록한 서버는 이 API에 나오지 않아요.
개인 대시보드에서 등록한 서버만 대상이에요.

성공 응답

200 OK

{
  "servers": [
    {
      "id": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
      "name": "블록마을",
      "slug": "block-town",
      "address": "play.example.com:25565",
      "edition": "java",
      "status": "published",
      "version": "1.21.1",
      "listing_kind": "server"
    }
  ]
}

서버가 없으면:

{
  "servers": []
}

servers[] 필드

필드	타입	null?	설명
id	string (UUID)	아니요	서버 고유 ID
name	string	아니요	표시 이름
slug	string	조건부	URL용 슬러그. 웹 상세 경로에 쓰일 수 있어요
address	string	아니요	접속 주소 (host_label). 도메인±포트 형태
edition	string	아니요	"java" 또는 "bedrock" 등 등록 시 값
status	string	아니요	예: "published", "draft"
version	string | null	예	감지·저장된 버전. 없으면 null
listing_kind	string | null	예	예: "server", "realm". 없으면 null

필드 이름

API JSON에서는 DB의 host_label을 address 로 노출해요.
클라이언트에서는 address만 사용하세요.

오류 응답

상태	조건	본문 예
401	키 없음/무효/폐기	{ "error": "Invalid or missing API key." }
429	1 RPS 초과	{ "error": "Rate limit exceeded", "limit": "1 rps" }
502	DB 조회 실패	{ "error": "Failed to load servers." }
502	인증 RPC 장애	{ "error": "Authentication service error." }

→ 오류·상태 코드, Rate limit

curl 예제

export MP_API_KEY="mp_live_YOUR_KEY"

curl -sS \
  -H "Authorization: Bearer ${MP_API_KEY}" \
  -H "Accept: application/json" \
  "https://api.mineplatform.kr/v1/servers" | jq .

공개 서버만 필터 (클라이언트 측):

curl -sS \
  -H "Authorization: Bearer ${MP_API_KEY}" \
  "https://api.mineplatform.kr/v1/servers" \
  | jq '.servers[] | select(.status=="published")'

웹 상세 페이지와 연결

슬러그가 있는 경우 대략 다음 형태로 열 수 있어요. (사이트 라우팅 기준)

https://mineplatform.kr/servers/{id}

정확한 경로는 웹앱 버전에 따라 다를 수 있으니, 연동 전에 한 번 브라우저로 확인하세요.

아직 없는 기능

지금은 아래를 지원하지 않아요.

• 서버 단건 조회 (/v1/servers/{id})
• 생성·수정·삭제
• status / edition 쿼리 필터
• 페이지네이션 커서 (limit/offset)
• 실시간 온라인 인원·핑 강제 재측정 (저장된 메타 조회)

필요하면 고객센터로 요청을 남겨 주세요. Changelog에 반영됩니다.