Nexon Open Api
AI 에이전트에는 아래 Markdown 원문 주소를 전달하세요.
Markdown 원문 보기

AI 에이전트 가이드

이 문서는 AI 에이전트가 읽도록 마크다운으로 제공됩니다. 사람이 읽을 API 사용법은 API 사용하기에 있습니다.

이 문서는 사람이 아니라 AI 에이전트가 NEXON Open API를 처음부터 끝까지 스스로 사용하도록 쓴 실행 가이드입니다. 도구 호출(tool calling)이 가능한 에이전트, 또는 에이전트를 만드는 개발자를 대상으로 합니다. 다른 가이드 문서가 "무엇을 제공하는가"를 설명한다면, 이 문서는 "자동으로 호출할 때 무엇이 어긋나는가"를 다룹니다. 여기 적힌 동작은 실제로 호출해 확인한 것이고, 「의무와 한도」는 공식 문서의 규칙을 옮긴 것입니다. 게임마다 제공 범위가 다르므로, 특정 게임의 예시 대신 모든 게임에 공통으로 적용되는 규칙만 담았습니다. 경로의 {game} 자리에는 사용할 게임의 식별자가 들어갑니다. 그 식별자는 스펙 파일의 경로(paths) 첫 구간입니다(「전체 스펙을 한 번에 확보하기」). 게임 이름으로 추측하지 마세요.

이 문서를 쓰는 법

  1. 「API Key는 게임 단위입니다」 — 어떤 게임에 쓸 수 있는 키인지 먼저 확인합니다.
  2. 「의무와 한도」 — 호출 허용량과 데이터 갱신 의무를 설계 전에 확인합니다.
  3. 「요청 방법」 — 인증 헤더를 적용합니다. 호출할 API에 date 파라미터가 있을 때만 「date 파라미터 규칙」도 읽습니다. date가 없는 API가 더 많습니다.
  4. 「에러 처리」 — 재시도해도 되는 코드와 안 되는 코드를 구분합니다.
  5. 「호출량은 먼저 세고 시작합니다」 — 화면 하나에 몇 번 호출되는지 세고 캐시를 붙입니다.
  6. 「에이전트 행동 지침」 — 마지막 체크리스트로 빠진 것을 확인합니다.

30초 요약

에이전트가 기억해야 할 최소 지식입니다.

항목 값
API 호스트 https://open.api.nexon.com. 이미지 같은 일부 정적 자산은 스펙 파일의 servers 에 적힌 다른 호스트
인증 HTTP 헤더 x-nxopen-api-key. Open ID 대상 API는 Authorization: Bearer {Access Token}. /static/ 메타데이터는 인증 없음
메서드 전부 GET
응답 형식 JSON
date 파라미터 일부 API에만 있다. 선택이면 생략이 최신, 필수이면 생략 시 400
키의 범위 게임(애플리케이션) 단위. 한 키로 다른 게임을 못 부른다
호출 허용량 개발 단계 초당 5건·하루 1,000건, 서비스 단계 초당 500건·하루 20,000,000건
데이터 갱신 의무 API로 크롤링한 데이터는 30일 이내에 갱신한다
조회 패턴 식별자 조회 API가 있는 게임은 이름 → 식별자 → 상세의 2단계. 없는 게임은 목록·검색 API를 바로 부른다
출처 표기 Data based on NEXON Open API

문서 사이트와 API 호스트는 다릅니다

문서 사이트는 https://openapi.nexon.com 이고, 실제 호출은 https://open.api.nexon.com 으로 보냅니다. 둘을 섞으면 경로가 통째로 실패합니다.

전체 흐름

에이전트가 거치는 단계는 다음과 같습니다. 각 단계에서 실패하는 방식이 다르므로, 한 단계씩 확인하고 넘어갑니다.

  1. 넥슨 ID로 로그인하고 애플리케이션을 등록해 API Key를 발급받습니다.
  2. 사용할 게임의 API 목록과 파라미터를 확인합니다.
  3. 이름을 식별자로 바꿉니다. 식별자 조회 API가 없는 게임은 이 단계를 건너뜁니다.
  4. 식별자로 상세 정보를 조회합니다.
  5. 에러 코드를 보고 재시도할지 중단할지 정합니다.
  6. 응답을 캐시하고, 화면에 출처를 표기합니다.

API Key는 게임 단위입니다

가장 자주 걸리는 지점입니다. NEXON Open API는 애플리케이션(키)을 게임별로 등록합니다. 한 키로 다른 게임의 경로를 부르면 경로 자체가 거부됩니다. 한 게임의 키로 다른 게임 경로를 호출하면 OPENAPI00006이 오고, 반대 방향도 같습니다. 이 코드를 "경로 오타"로만 해석하면 원인을 찾지 못합니다.

상황 응답 에이전트가 할 일
키에 등록된 게임의 경로 200 정상
키에 등록되지 않은 게임의 경로 400 OPENAPI00006 그 게임의 키를 따로 발급받는다. 재시도는 무의미
존재하지 않는 경로 400 OPENAPI00006 위와 코드가 같다. 경로와 키 등록 상태를 함께 확인한다

여러 게임을 다룰 때

게임마다 키를 따로 보관하고, 요청 경로의 첫 구간을 보고 키를 고르도록 만듭니다. 키를 하나만 두면 게임을 늘리는 순간 조용히 전부 실패합니다. 호출 허용량도 애플리케이션 단위로 합산되므로, 게임별로 나누면 허용량도 나뉩니다. 진단 코드도 같은 키 선택 규칙을 타야 합니다. 권한을 확인하는 코드가 기본 키만 쓰면, 게임별 키가 있는데도 "막힘"으로 잘못 보고합니다.

NXOPEN_API_KEY_{게임A}=...      경로 첫 구간이 {게임A} 면 이 키
NXOPEN_API_KEY_{게임B}=...      경로 첫 구간이 {게임B} 면 이 키

의무와 한도

공식 문서 사전 준비하기에 있는 규칙입니다. 설계 단계에서 알아야 하므로 여기에 옮겨 둡니다.

데이터 갱신 의무

API를 통해 데이터를 크롤링한 경우 30일 이내에 크롤링한 데이터를 갱신해야 할 의무가 있습니다. 응답을 저장한다면 받은 시각을 함께 남기고, 30일이 지나기 전에 다시 받도록 만듭니다. 짧은 캐시와 별개로, 오래 보관하는 데이터에도 만료가 필요합니다.

애플리케이션 타입과 호출 허용량

애플리케이션 타입 초당 최대 허용량 1일 최대 허용량
개발 단계 5건 1,000건
서비스 단계 500건 20,000,000건

개발 단계로 만들어 테스트하고, 서비스 URL이 준비되면 서비스 단계 애플리케이션을 새로 등록하는 것이 공식 권장 순서입니다. 서비스 단계로 옮길 때는 API Key를 새로 발급받아야 합니다.

발급 규칙

  1. API Key는 애플리케이션마다 최대 2개까지 발급됩니다.
  2. 넥슨 ID 하나로 같은 게임의 애플리케이션을 최대 3개까지 등록할 수 있습니다.

식별자는 비밀로 취급합니다

이름으로 조회해 받는 식별자는 내부 데이터를 조회하기 위한 값이지, 화면에 노출해도 되는 값이 아닙니다. 실측 결과 식별자의 길이가 32자 또는 64자로 일정하지 않았고, 64자로 오는 경우 뒤쪽 32자가 사용 중인 API Key의 뒤 32자와 같았습니다. 이 32자는 발급 계정에 묶인 값입니다.

식별자의 구조

API Key   {환경}_..............................<계정에 묶인 32자>
식별자     <대상마다 다른 32자><계정에 묶인 32자>

길이가 판별 기준이 되지는 않습니다 — 64자인데 키 조각을 포함하지 않는 경우도 있습니다.

식별자가 바뀔 수 있다고 공지한 게임도 있습니다. 식별자를 오래 저장하지 말고, 저장한다면 이름으로 다시 받아 갱신하는 경로를 두세요.

지켜야 할 것

길이는 판별 기준이 되지 않습니다. 판별하려 하지 말고, 저장하기 직전에 실제 값을 검사하는 편이 안전합니다.

하지 말 것 대신
캐시·로그 파일명에 식별자 값을 넣기 파라미터 이름만 넣고 값은 해시로 바꾼다
로그와 에러 메시지에 식별자 원문 남기기 앞 8자만 남긴다
프론트엔드로 식별자를 내려 URL에 싣기 서버 안에서만 사용한다
문서나 이슈에 실제 응답을 그대로 붙이기 값을 가공해서 붙인다

검사를 코드로 옮깁니다

규칙을 사람의 주의력에 맡기지 마세요. 응답을 저장하기 직전에 API Key 의 뒤 32자가 본문에 들어 있는지 확인하고, 있으면 저장을 건너뛰는 편이 확실합니다.

저장 스키마

식별자 컬럼은 64자 이상으로 잡습니다. 32자로 고정하면 64자로 오는 경우에 잘립니다.

요청 방법

모든 API는 GET이고, 요청 본문은 사용하지 않습니다. 인증 헤더는 API마다 다르며, 스펙에서 in: header 로 적힌 파라미터가 그 API의 인증 헤더입니다.

대상 헤더 값
대부분의 API x-nxopen-api-key 발급받은 API Key
Open ID 대상 API Authorization Bearer {Access Token}
경로가 /static/ 으로 시작하는 메타데이터 없음 인증 없이 받는다

Open ID 대상 API

스펙의 카테고리 이름에 Open ID가 붙은 API는 사용자 본인의 제공 동의가 필요한 데이터입니다. API Key가 아니라, 사용자가 NEXON Open ID로 로그인해 발급된 Access Token으로 부릅니다. Access Token은 서버에서만 다룹니다. NEXON Open ID는 프렌즈 프로그램으로 제공되며, 개발 가이드는 넥슨 계정으로 로그인해야 볼 수 있습니다.

인증 없이 받는 메타데이터와 다른 호스트

경로가 /static/ 으로 시작하는 메타데이터는 정적 JSON이라 API Key 없이 받을 수 있습니다. 응답에 담긴 코드 값을 이름이나 이미지로 바꿀 때 씁니다. 키가 없는 게임이라도 메타데이터만으로 만들 수 있는 화면이 있습니다. 경로에 {language_code} 같은 자리표시자가 있으면 쿼리 파라미터가 아니라 경로 치환입니다. 쿼리 문자열 생성기가 채워 주지 않으니 직접 넣습니다. 스펙 파일마다 servers 가 따로 있고, 이미지처럼 API 호스트가 아닌 곳을 가리키는 파일이 있습니다. 그 경로를 API 호스트로 부르면 400이 옵니다. 여러 스펙 파일을 합칠 때 servers 를 버리지 마세요.

응답 형식

정상 응답은 요청한 데이터가 담긴 JSON 입니다. 실패는 error 객체 안에 name 과 message 가 담겨 옵니다. message 를 사용자 화면에 그대로 쓰지 마세요 — 아래 「사용자에게 보여줄 문구」 를 참고하세요.

{ "error": { "name": "OPENAPI00004", "message": "Please input valid parameter" } }

파라미터 인코딩

이름처럼 한글이 들어가는 값은 URL 인코딩이 필요합니다. 직접 문자열을 이어붙이지 말고 쿼리 문자열 생성기를 쓰는 편이 안전합니다. 아래 예시의 중괄호는 자리표시자입니다. 식별자 파라미터의 이름은 게임마다 달라서 스펙 전수로 보면 다섯 가지 이상이 쓰이고 있습니다. 추측하지 말고 스펙에서 읽으세요.

# 1) 이름으로 식별자를 받는다
curl -G 'https://open.api.nexon.com/{game}/v1/id' \
  --data-urlencode '{이름_파라미터}=대상이름' \
  -H 'x-nxopen-api-key: YOUR_API_KEY_HERE'

# 2) 받은 식별자로 상세를 받는다. date 를 생략하면 최신이다.
curl -G 'https://open.api.nexon.com/{game}/v1/{리소스}' \
  --data-urlencode '{식별자_파라미터}=RECEIVED_IDENTIFIER' \
  -H 'x-nxopen-api-key: YOUR_API_KEY_HERE'

# 파라미터 이름은 게임마다 다르다. 스펙에서 읽고 쓴다.

date 파라미터 규칙

date 파라미터는 일부 API에만 있습니다. 호출할 API의 스펙에서 date가 있는지, 있다면 필수인지 먼저 확인합니다. 선택인 API와 필수인 API는 규칙이 다릅니다.

아래 표의 '오늘'·'어제'는 그 API의 기준 시간대로 셉니다. 기준 시간대는 스펙의 date 설명에 적혀 있고(KST 외에 SGT·TST 처럼 서비스 지역 시간을 쓰는 게임이 있습니다), 같은 게임 안에서도 API마다 다른 경우가 있습니다. 서버의 현지 시각으로 계산하지 마세요.

date가 선택인 API

date 값 결과
생략 200. 최신 데이터. 응답의 date 필드는 null
어제 200. 하루 전 스냅샷
오늘 400 OPENAPI00004
미래 400 OPENAPI00004
서비스 개시 이전 날짜 200. 단, 요청한 날짜 외 전 필드가 null

date가 필수인 API

랭킹처럼 date가 필수인 API는 생략하면 최신 값이 아니라 에러가 옵니다. 선택인 API와 달리 오늘 날짜도 받습니다.

date 값 결과
생략 400 OPENAPI00004
어제 200
오늘 200
미래 400 OPENAPI00009
조회 가능한 첫 날짜 이전 400 OPENAPI00009 또는 OPENAPI00004 — API마다 다르다

오늘 날짜는 그날 데이터가 집계된 뒤에만 조회됩니다(아래 「데이터가 열리는 시각」). 기본값은 어제로 둡니다.

미래 날짜는 OPENAPI00009(데이터 준비 중)로 옵니다. 조회 가능한 첫 날짜보다 이전인 과거 날짜도 00009 로 오는 API 가 있습니다.

데이터가 열리는 시각

그날 데이터를 언제부터 조회할 수 있는지는 API마다 다르고, 스펙의 description 에 적혀 있습니다. 전일 데이터가 다음날 새벽에야 열리는 API도 있고, 오늘 순위가 오전 중에 열리는 API도 있습니다. 그 시각 전에는 해당 날짜의 데이터가 없습니다. 날짜를 자동으로 채우는 코드는 자정이 아니라 description 에 적힌 시각을 기준으로 삼습니다.

조회 가능 구간은 API마다 다릅니다

거슬러 올라갈 수 있는 범위는 API마다 다르고, 조회 가능한 첫 날짜도 description 에 적혀 있습니다. 문서에 적힌 범위와 실제 동작이 다른 경우가 있으므로, 날짜 입력 UI를 만들기 전에 경계값을 직접 호출해 확인하는 것을 권합니다. 조회 범위가 엔드포인트가 아니라 스펙 맨 앞(info)에만 적힌 게임도 있습니다 — 아래 「스펙을 그대로 믿지 않습니다」.

에러 처리

에이전트에게 가장 중요한 절입니다. 재시도하면 안 되는 코드를 재시도하면 허용량만 두 배로 씁니다.

코드 응답 재시도 이유
OPENAPI00001 500 예 서버 내부 오류. 백오프 후 재시도
OPENAPI00002 403 아니오 권한 없음. 키와 대상 확인
OPENAPI00003 400 아니오 유효하지 않은 식별자. 같은 요청을 다시 보내도 결과가 바뀌지 않음
OPENAPI00004 400 아니오 파라미터 누락 또는 대상 없음. 시간이 지나도 바뀌지 않음
OPENAPI00005 400 아니오 유효하지 않은 API Key
OPENAPI00006 400 아니오 키에 등록되지 않은 게임이거나 잘못된 경로
OPENAPI00007 429 예 호출량 초과. 백오프 필수
OPENAPI00009 400 예 데이터 준비 중. 잠시 후 재시도. 단 date 를 넣은 요청이나 범위 밖의 입력에도 오므로, 한 번 재시도해도 같으면 멈춘다
OPENAPI00010 400 예 게임 점검 중
OPENAPI00011 503 예 API 점검 중

재시도는 백오프와 지터로

고정 간격으로 재시도하면 여러 요청이 같은 시점에 몰려 OPENAPI00007 을 다시 만듭니다. 지수 백오프에 지터를 더해 흩뜨리세요.

사용자에게 보여줄 문구

에러 코드의 공식 설명을 그대로 화면에 쓰지 않습니다. OPENAPI00004는 설명이 "파라미터 누락 또는 유효하지 않음"이지만, 존재하지 않는 이름으로 조회해도 같은 코드가 옵니다. 화면에 "잘못된 파라미터"라고 쓰면 사용자는 자기 입력이 아니라 서비스 고장으로 이해합니다. "해당 이름을 찾을 수 없습니다"처럼 상황에 맞는 문구로 바꿔 주세요.

1단계 성공을 존재 확인으로 쓰지 않습니다

이름으로 식별자를 받는 데 성공해도, 그 식별자로 상세를 조회할 때 OPENAPI00003이 오는 경우가 있습니다. 2단계까지 가 봐야 조회 가능 여부를 알 수 있습니다. 따라서 1단계가 성공한 시점에 "찾았습니다"를 표시하지 않는 편이 좋습니다.

같은 "없음" 인데 신호가 다릅니다

전부 "없음" 인데 형태가 다릅니다. 화면 문구는 "기록 없음" 으로 맞춰 주세요.

상황 응답
기록이 없는 항목 200 + 해당 필드가 0 (null 이 아닌 경우가 있다)
등록되지 않은 하위 리소스 OPENAPI00004 — 파라미터 오류가 아니다
그날 데이터 없음 200 + 전 필드 null
권한 밖의 대상 OPENAPI00004 또는 OPENAPI00003 — 권한 문제인데 파라미터 오류처럼 온다
조건은 맞는데 결과가 0건 (대상을 지정한 목록 조회 포함) 200 + 빈 배열
값이 없는 칸 null 대신 "(Unknown)" 같은 자리표시 문자열이 오는 게임이 있다

HTTP 200이 성공을 뜻하지 않는 경우

에러 없이 200이 오는데 요청한 날짜 외 전 필드가 null인 응답이 있습니다. 서비스 개시 이전 날짜로 조회했을 때가 그렇습니다. 상태 코드와 에러 코드만 확인하는 구현은 이 응답을 정상으로 받아들여 빈 값을 저장하게 됩니다. 핵심 필드가 null인지 함께 확인해 주세요.

# 서비스 개시 이전 날짜로 조회하면 에러가 아니라 200 이 온다.
curl -G 'https://open.api.nexon.com/{game}/v1/{리소스}' \
  --data-urlencode '{식별자_파라미터}=RECEIVED_IDENTIFIER' \
  --data-urlencode 'date=2023-12-20' \
  -H 'x-nxopen-api-key: YOUR_API_KEY_HERE'

# HTTP 200
# { "date": "2023-12-20T00:00+09:00", "<이름 필드>": null, "<레벨 필드>": null, ... }   ← 요청한 날짜만 채워지고 나머지는 null
#
# 상태 코드와 에러 코드만 보는 구현은 이것을 정상으로 받아들인다.
# 핵심 필드가 null 인지 함께 확인한다. date 필드로 판정하지 않는다 — date 를 생략한 정상 응답도 date 가 null 이다.

enum 밖의 값이 400 이 아니라 조용히 무시되는 파라미터도 있습니다. 필터 값에 오타나 옛 이름을 넣었는데 에러 없이 필터만 빠진 전체 결과가 200 으로 오고, 같은 API 안에서도 파라미터마다 다릅니다. 필터 값은 스펙의 enum 에서만 고르고, 응답 행의 해당 필드가 요청한 값과 같은지 확인하세요.

호출량은 먼저 세고 시작합니다

"초당 몇 건"이라는 숫자만으로는 감이 오지 않습니다. 화면 하나를 그리는 데 몇 번 호출되는지 먼저 세어 보면 캐시가 선택이 아니라는 것이 분명해집니다. 아래는 프로필 카드 한 장을 그릴 때의 실측입니다.

단계 호출 수
이름 → 식별자 1
기본 정보 1
능력치·상세 정보 6
합계 8

순위를 얹으면 두 배가 됩니다

위 8회는 기본 프로필 기준입니다. 카드에 순위 배지를 넣으면 13~15회가 됩니다. 랭킹 API는 한 번에 한 종류의 순위만 돌려주기 때문입니다. 개발 단계 키로는 카드 한 장도 한 번에 그리지 못합니다. 캐시를 먼저 만들고 시작하는 편이 빠릅니다.

한 대상의 순위는 목록을 훑지 않고 묻습니다

목록·랭킹 API 에 식별자 파라미터가 있으면, 넣었을 때 그 대상의 행만 돌아옵니다(다른 필터는 그대로 적용됩니다). 특정 대상의 순위를 찾으려고 페이지를 훑으면 호출이 수백 배가 됩니다. 다만 선택 파라미터의 기본값이 조회 구간을 정하는 API 가 있습니다. 대상을 지정한 조회가 0건이면 "기록 없음" 으로 확정하기 전에, 그 대상이 속한 구간 값으로 한 번 더 물으세요. 기본값은 스펙 description 에만 적혀 있습니다.

캐시 효과

게임 데이터는 갱신 주기가 길어 (엔드포인트, 식별자, date) 조합의 캐시가 잘 듣습니다. 캐시 하나로 16배입니다. 캐싱은 성능 최적화가 아니라 이 API 를 쓰는 기본 전제로 보세요. 동시성은 세마포어나 토큰 버킷으로 허용량 아래에 묶고, 모든 호출에 타임아웃을 겁니다. 한 조회의 실패가 화면 전체를 막지 않도록 격리하세요.

항목 값
캐시 미적중 179ms
캐시 적중 11ms
순차 호출 통과 속도 8.0 req/s (20회 연속, 429 없음)

API에 없는 집계를 만들 때

"직업별 인구"나 "전투력 순위"처럼 API가 직접 주지 않는 값은 랭킹을 여러 페이지 모아 직접 세는 수밖에 없습니다. 이때 두 가지를 주의합니다.

  1. 표본은 전체 사용자가 아니라 랭킹 상위 N명입니다. 화면에 표본 범위를 같이 적지 않으면 전체 분포로 읽힙니다.
  2. 랭킹 응답에 식별자가 없는 경우, 상세 값을 붙이려면 대상마다 추가 호출이 필요합니다. 비용이 표본 수만큼 곱해집니다.

무엇을 근거로 셌는지 함께 남깁니다

집계 결과를 낼 때는 표본 범위를 응답에 같이 실어 두세요. 나중에 숫자만 남으면 해석할 수 없습니다.

목록을 넘길 때

  • page 는 1부터입니다. 0 은 OPENAPI00004 입니다.
  • 끝을 넘긴 페이지는 빈 배열이 오는 게임과 OPENAPI00004 가 오는 게임이 있습니다. 둘 다 "끝" 으로 처리하세요.
  • 한 페이지의 건수는 고정이 아닙니다. 동순위가 있으면 기본 크기보다 많거나 적게 옵니다. 순위를 (page−1)×크기+i 로 계산하지 말고 응답의 순위 필드를 쓰고, "기본 크기 미만이면 마지막 페이지" 로 판정하지 마세요.
  • cursor 로 넘기는 목록은 정렬 방향을 먼저 확인하세요. 오래된 것부터 오면 최신 값 하나에 페이지 수만큼 호출이 듭니다. 형식이 틀린 cursor 에 OPENAPI00003 을 돌려주는 게임이 있고, 쪽을 건너뛸 수 없습니다.

응답 필드에서 실제로 걸린 것

필드 이름만 보고 의미를 넘겨짚으면 틀리는 경우가 있습니다.

넘겨짚기 쉬운 것 실제
..._part 류가 장착 부위일 것이다 아이템 종류인 경우가 있다. 부위는 ..._slot 쪽이다
기록이 없으면 null일 것이다 0으로 오는 필드가 있다. null 검사로는 못 거른다
숫자 필드는 숫자일 것이다 문자열로 오는 것이 있다. 비교·정렬 전에 변환한다
목록형 필드는 객체일 것이다 배열인 경우가 있다. 이름으로 찾아 써야 한다
시각 필드는 KST 일 것이다 Z(UTC)로 오는 게임이 있다. 아래 「응답의 시각 필드」

응답의 시각 필드

응답에 담긴 시각의 시간대는 게임마다 다릅니다. +09:00 으로 오는 게임도 있고, Z(UTC, 밀리초 포함)로 오는 게임도 있습니다. 문자열의 앞 10자를 잘라 날짜로 쓰면 UTC 응답에서는 하루가 밀립니다. 파싱한 뒤 서비스의 기준 시간대로 바꾸세요. date 파라미터의 기준 시간대는 「date 파라미터 규칙」을 보세요.

모르는 값이 와도 버리지 않습니다

게임 업데이트로 새 슬롯이나 새 등급이 추가될 수 있습니다. 화이트리스트에 없다고 버리면 업데이트 때마다 조용히 데이터가 사라집니다. 모르는 값은 뒤에 붙여 두고 로그로 남기는 편이 안전합니다.

전체 스펙을 한 번에 확보하기

게임마다 API 문서를 눌러 보는 대신, 스펙 파일을 받아 한 번에 읽으면 에이전트가 다룰 수 있는 형태가 됩니다. 어떤 게임에 어떤 엔드포인트가 있는지 목록으로 만들어 두면 경로를 추측할 일이 없어집니다.

# 제공 중인 게임과 스펙 파일의 목록
curl -s 'https://openapi.nexon.com/static/script/specification.json'

# 목록에 적힌 경로로 게임별 OpenAPI 스펙을 받는다.
# 받아 두면 엔드포인트·파라미터·필수 여부를 에이전트가 직접 읽을 수 있다.
# 스펙 파일의 경로(paths) 첫 구간(/{game}/v1/...)이 URL 에 쓸 게임 식별자다.
#
# 주의: 스펙의 required 가 조건부 필수를 표현하지 못하는 경우가 있다.
# required 가 false 여도 description 에 조건이 적혀 있으면 그 조건을 따른다.

스펙을 그대로 믿지 않습니다

required 가 false 인데 설명에 조건이 적힌 파라미터가 있습니다. 조건을 만족하는 요청에서 그 값을 빼면 OPENAPI00004 가 납니다. 스펙은 "조건부 필수"를 표현하지 못합니다. 새 엔드포인트를 쓸 때는 description 까지 읽으세요. 응답 스키마도 실제와 다를 수 있습니다. 필드 이름, 숫자와 문자열, 배열과 객체, 최상위가 배열인지 객체인지가 다르게 온 사례가 있고, nullable 표시가 없는 필드에도 null 이 옵니다. 파싱 코드를 쓰기 전에 엔드포인트마다 실제 응답 한 건을 스키마와 대조하고, 다른 곳은 실제를 따르세요. 게임 전체에 걸친 규칙 — 데이터 반영 지연, 조회 가능한 첫 날짜, 식별자가 바뀔 수 있다는 공지 — 는 엔드포인트가 아니라 스펙 맨 앞의 info.description 에만 적힌 경우가 있습니다. date 가 없는 게임도 info 를 먼저 읽으세요. info 의 날짜가 실제와 다른 사례도 있으니 경계값은 직접 호출로 확인합니다.

스펙을 내려받을 때

  1. 인증이 필요 없습니다. 스펙 인덱스와 각 스펙 파일은 키 없이 받을 수 있습니다.
  2. 받은 원본을 바이트 그대로 보관하세요. 줄바꿈을 변환하면 파서 검증이 의미를 잃습니다.
  3. 파싱에 실패하면 조용히 넘기지 말고 멈추세요. 배포 형식이 바뀌었다는 신호입니다.

에이전트 행동 지침

구현을 마친 뒤 아래 항목을 점검합니다.

반드시 지킬 것

  1. API Key는 서버에만 두고, 프론트엔드나 저장소에 넣지 않습니다.
  2. date가 선택인 API에서는 필요할 때만 넣고, 최신 값이 필요하면 생략합니다. date가 필수인 API에서는 생략하지 않습니다.
  3. 재시도는 429·5xx·점검 중 코드에만 겁니다. 백오프를 함께 씁니다.
  4. 200을 받아도 핵심 필드가 null인지 확인합니다.
  5. 응답을 캐시하고, 캐시 키에 식별자 원문을 넣지 않습니다.
  6. 화면에 Data based on NEXON Open API를 표기합니다.
  7. 응답을 저장하면 30일 이내에 다시 받아 갱신합니다.
  8. 설계한 호출량이 애플리케이션 타입의 허용량 안에 드는지 확인합니다.
  9. 필터 값은 스펙의 enum 에서만 고르고, 응답 행이 요청한 필터와 맞는지 확인합니다.

하지 말 것

  1. 식별자를 로그·파일명·URL에 원문으로 남기지 않습니다.
  2. OPENAPI00003·00004·00006을 재시도하지 않습니다.
  3. 1단계 조회 성공을 대상 존재 확인으로 쓰지 않습니다.
  4. 에러 코드의 공식 설명을 사용자 문구로 그대로 쓰지 않습니다.
  5. 표본 범위를 적지 않은 채 집계 결과를 전체 통계처럼 보여주지 않습니다.
  6. 특정 대상의 순위를 찾으려고 목록 페이지를 훑지 않습니다. 식별자 파라미터로 바로 묻습니다.

표준 호출 절차

1. 경로의 첫 구간으로 이 게임의 API Key 를 고른다
2. 이름 → 식별자          (식별자 조회 API가 있을 때. 실패하면 즉시 중단. 재시도 안 함)
3. 식별자 → 상세          (최신이 필요하면 date 를 생략)
4. 200 이어도 핵심 필드가 null 인지 확인한다
5. 성공 응답을 캐시에 넣는다 (키에 식별자 원문 금지)
6. 화면에 출처를 표기한다

함께 볼 문서

이 페이지는 자동 호출에서 어긋나는 지점만 다룹니다. 서비스 소개와 기본 사용법은 아래 문서를 참고하세요.

  1. 사전 준비하기 — 넥슨 ID 로그인과 애플리케이션 등록 절차
  2. API 사용하기 — API 조회·테스트와 에러 코드 표
  3. 게임 — 게임별 엔드포인트와 파라미터
  4. 공지사항 — 엔드포인트 추가·변경 이력. 이 문서의 동작이 실제와 다르면 먼저 확인할 곳
  5. 이용약관 — 제작한 애플리케이션에 적용되는 조건
  6. 프렌즈 프로그램 신청 — Open ID 대상 API를 쓰려면 필요한 절차 (로그인 필요)

용어

용어 뜻
애플리케이션 API Key 발급 단위. 게임별로 등록한다
API Key 헤더 x-nxopen-api-key 에 싣는 인증 값. 애플리케이션 등록 시 발급된다
식별자 이름으로 조회해 받는 내부 조회용 값. 비밀로 취급한다
허용량 애플리케이션 단위로 합산되는 호출 한도
스펙 게임별 엔드포인트·파라미터를 담은 OpenAPI 문서