문서 › API
API 키 사용 방법
API 키를 발급해 상품 목록·상품 정보를 불러오고 무료 상품·구매한 상품 파일을 다운로드하는 방법
API 키를 발급하면 프로그램(서버 플러그인, 봇, 스크립트 등)에서 Modern Service의 상품 목록·상품 정보를 불러오고, 무료 상품과 내가 구매한 유료 상품의 파일을 자동으로 다운로드할 수 있습니다.
유료 상품은 API 키를 발급한 계정으로 구매한 경우에만 다운로드할 수 있습니다. 구매하지 않은 유료 상품은 거부됩니다.
API 키 발급
- Modern Service에 로그인합니다.
- 오른쪽 위 프로필 → 내 계정 › API 관리로 이동합니다.
- 키 이름(예:
서버 자동 업데이트)을 입력하고 API 키 발급을 누릅니다. - 화면에 표시된 키(
ms_로 시작)를 바로 복사해 안전한 곳에 보관합니다. 키는 발급 직후 한 번만 표시됩니다.
- 계정당 최대 5개까지 발급할 수 있습니다.
- 키를 잃어버렸거나 유출이 의심되면 폐기하고 새로 발급하세요. 폐기한 키는 즉시 사용할 수 없습니다.
인증
모든 요청은 GET 방식이며, 요청 헤더에 API 키를 넣습니다.
Authorization: Bearer ms_발급받은_키X-API-Key: ms_발급받은_키 헤더도 사용할 수 있습니다.
- 기본 주소:
https://www.mservice.kr/api/v1 - 응답 형식: JSON (파일 다운로드 제외)
요청 제한
| 항목 | 제한 |
|---|---|
| 호출 횟수 | API 키당 1분에 120회 |
| 초과 시 | 429 rate_limited 응답 — 잠시 후 다시 시도 |
응답 헤더의 RateLimit-Remaining, RateLimit-Reset으로 남은 횟수와 초기화 시간을 확인할 수 있습니다.
상품 목록
GET https://www.mservice.kr/api/v1/products| 파라미터 | 설명 | 예시 |
|---|---|---|
q | 검색어 (이름·요약·카테고리) | 경제 |
type | 종류 | plugin 또는 mod |
price | 가격 | free 또는 paid |
sort | 정렬 | downloads(기본), newest, updated |
page | 페이지 (1부터) | 2 |
limit | 페이지당 개수 (1~100, 기본 20) | 50 |
curl -H "Authorization: Bearer ms_..." "https://www.mservice.kr/api/v1/products?type=plugin&price=free&sort=newest&limit=10"{
"items": [ { "id": 12345678, "slug": "my-plugin", "title": "…", "free": true, "...": "..." } ],
"page": 1,
"limit": 10,
"total": 42,
"pages": 5
}상품 정보
GET https://www.mservice.kr/api/v1/products/{id}{id}에는 8자리 상품 번호 또는 슬러그를 넣습니다. 상품 번호는 상품 페이지의 ⋮ 메뉴 → 번호 복사로 얻을 수 있습니다. 응답에는 설명(description, 마크다운)과 버전 목록(versions)이 함께 포함됩니다.
curl -H "Authorization: Bearer ms_..." https://www.mservice.kr/api/v1/products/12345678상품 응답 필드
| 필드 | 설명 |
|---|---|
id | 8자리 상품 번호 |
slug, title, summary | 주소용 이름, 상품명, 한 줄 소개 |
type | plugin 또는 mod |
price, free | 가격(포인트), 무료 여부 |
url, icon_url | 상품 페이지 주소, 아이콘 주소 |
downloads, followers | 다운로드 수, 팔로워 수 |
rating | { "average": 4.8, "count": 12 } |
categories, loaders, game_versions | 카테고리, 로더/플랫폼, 지원 마인크래프트 버전 |
environments | 모드의 지원 환경 (client, server) |
source_url, docs_url | 소스 코드 주소, 문서 주소 |
latest_version | 최신 버전 { id, version, channel, created_at } |
created_at, updated_at | 등록일, 업데이트일 (ISO 8601, UTC) |
버전 목록
GET https://www.mservice.kr/api/v1/products/{id}/versions| 필드 | 설명 |
|---|---|
id | 버전 ID (다운로드 시 사용) |
version, channel | 버전 번호, 채널 (release, beta, alpha) |
changelog | 변경 사항 (마크다운) |
game_versions, loaders | 지원 버전, 로더/플랫폼 |
file_name, file_size, downloads | 파일 이름, 크기(바이트), 다운로드 수 |
download_url | 다운로드 주소 — 구매하지 않은 유료 상품은 null |
파일 다운로드 (무료 상품 · 구매한 유료 상품)
GET https://www.mservice.kr/api/v1/products/{id}/download
GET https://www.mservice.kr/api/v1/products/{id}/download?version={버전 ID}version을 생략하면 최신 버전을 받습니다. 파일 이름은 Content-Disposition 헤더로 전달됩니다.
# 최신 버전을 원래 파일 이름으로 저장
curl -L -OJ -H "Authorization: Bearer ms_..." https://www.mservice.kr/api/v1/products/12345678/download언어별 예시
JavaScript (Node.js 18+)
const KEY = process.env.MSERVICE_API_KEY;
const res = await fetch('https://www.mservice.kr/api/v1/products?type=plugin&price=free', {
headers: { Authorization: `Bearer ${KEY}` },
});
if (!res.ok) throw new Error((await res.json()).message);
const { items } = await res.json();
console.log(items.map(p => `${p.title} ${p.latest_version?.version}`));Python
import os, requests
KEY = os.environ["MSERVICE_API_KEY"]
headers = {"Authorization": f"Bearer {KEY}"}
info = requests.get("https://www.mservice.kr/api/v1/products/12345678", headers=headers).json()
print(info["title"], info["latest_version"]["version"])
# 무료 상품 또는 구매한 상품의 최신 파일 저장
r = requests.get("https://www.mservice.kr/api/v1/products/12345678/download", headers=headers)
r.raise_for_status()
open(info["versions"][0]["file_name"], "wb").write(r.content)오류 응답
오류가 나면 HTTP 상태 코드와 함께 다음 형식으로 응답합니다.
{ "error": "paid_product", "message": "구매하지 않은 유료 상품입니다. ..." }| 상태 | error | 의미 |
|---|---|---|
| 401 | unauthorized | API 키를 넣지 않음 |
| 401 | invalid_key | 잘못되었거나 폐기된 키, 또는 이용이 정지된 계정 |
| 403 | paid_product | 구매하지 않은 유료 상품을 다운로드하려고 함 |
| 404 | not_found | 상품을 찾을 수 없음 (비공개 상품 포함) |
| 404 | version_not_found | 버전을 찾을 수 없음 |
| 405 | method_not_allowed | GET 이외의 요청 |
| 429 | rate_limited | 요청 제한 초과 |
보안 수칙
- API 키는 비밀번호와 같습니다. GitHub 등 공개 저장소나 클라이언트(브라우저·모드 코드)에 넣지 마세요.
- 서버의 환경 변수(예:
MSERVICE_API_KEY)나 설정 파일에 보관하세요. - 용도별로 키를 따로 발급하면, 문제가 생긴 키만 폐기할 수 있습니다.
- 내 계정 › API 관리에서 키별 마지막 사용 시각을 확인할 수 있습니다. 쓰지 않는 키는 폐기하세요.
마지막 수정: 2026. 11. 10. 18:29