API 사용하기
애플리케이션 등록 후, API Key 발급이 완료되었다면 문서를 살펴봅니다. (API Key는 내 애플리케이션 > 애플리케이션 상세 페이지에서 확인할 수 있습니다.) API 요청은 간단하지만 요청할 때 알아야 할 몇 가지 세부 사항이 있습니다.
API 조회
상단 메뉴 > 게임 메뉴에서 NEXON Open API를 통해 제공되는 게임별 API 목록을 확인하실 수 있습니다. API마다 다음과 같은 정보를 제공하고 있습니다.
API 정보
API에 대한 설명과 실제 사용될 요청 URL을 제공합니다. API 호출 시 함께 전송이 필요한 요청 파라미터는 Parameters에 표기되어 있으며, 파라미터에 대한 설명은 Description에 제공됩니다.
요청 파라미터 (Parameters)
Open API를 호출할 때 함께 서버로 전송해야 하는 파라미터의 정보를 나타냅니다. 필수값(*required)으로 표시된 파라미터들은 API 호출 시 누락되지 않도록 주의하셔야 합니다.
응답 정보 (Responses)
Open API를 호출한 후 받는 응답 정보들을 제공합니다. Response Description은 API를 정상적으로 호출할 경우 받는 데이터에 대한 설명이나 구조에 대한 설명을 제공합니다. Response Headers와 Response Body는 API를 테스트할 때 사용되며, 자세한 설명은 아래의 API 테스트 항목을 참조하세요.
API 사용
게임 메뉴에서 조회한 요청 URL을 호출하면 Open API를 사용하실 수 있으며, API에 따라 필요한 요청 파라미터를 함께 전송하셔야 합니다. NEXON Open API에서 제공되는 Open API를 호출할 때는, API Key 값을 Header에 포함하셔야 정상적으로 사용할 수 있습니다.
Type | Key name | Content type |
---|---|---|
Header | x-nxopen-api-key | String |
API 사용 중 에러가 발생할 경우, 응답코드 값을 보고 에러사유를 판단할 수 있습니다. 아래의 응답코드 표를 참고하세요.
에러 코드 | 응답 코드 | 응답명 | 설명 |
---|---|---|---|
OPENAPI00001 | 500 | Internal Server Error | 서버 내부 오류 |
OPENAPI00002 | 403 | Forbidden | 권한이 없는 경우 |
OPENAPI00003 | 400 | Bad Request | 유효하지 않은 식별자 |
OPENAPI00004 | 400 | Bad Request | 파라미터 누락 또는 유효하지 않음 |
OPENAPI00005 | 400 | Bad Request | 유효하지 않은 API KEY |
OPENAPI00006 | 400 | Bad Request | 유효하지 않은 게임 또는 API PATH |
OPENAPI00007 | 429 | Too Many Requests | API 호출량 초과 |
OPENAPI00009 | 400 | Bad Request | 데이터 준비 중 |
OPENAPI00010 | 400 | Bad Request | 게임 점검 중 |
OPENAPI00011 | 503 | Service Unavailable | API 점검 중 |
API 테스트
NEXON Open API에서 제공되는 Open API들은 모두 게임 메뉴 내에서 직접 테스트해 보고 그에 대한 응답 값을 조회해 볼 수 있습니다. (테스트 기능은 넥슨 ID로 로그인하고, 테스트를 희망하는 API의 API Key를 발급 받은 상태에서만 사용할 수 있습니다.)
- 게임 > 게임선택 > API 목록에서 테스트하고자 하는 API를 선택합니다.
- Try it out 버튼을 클릭합니다.
- Parameters(요청 파라미터) 입력란에 요청 파라미터를 입력합니다.
- Execute 버튼을 클릭하여 API를 호출합니다.
- 다음과 같은 정보를 확인합니다.
- Curl / Request URL : 입력한 요청 파라미터 값을 포함하여 실제로 호출된 URL
- 응답 정보(Server response)
- Code : Http 상태 코드로 요청 결과의 상태
- Response Headers : 응답받은 정보의 헤더 값
- Response Body : 응답받은 정보의 데이터
API 샘플코드
Java 샘플코드
import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;
public class ApiExample {
public static void main(String[] args) {
try {
String API_KEY = "YOUR API KEY HERE";
String characterName = URLEncoder.encode("CHARACTER NAME", StandardCharsets.UTF_8);
String urlString = "https://open.api.nexon.com/heroes/v1/id?character_name=" + characterName;
URL url = new URL(urlString);
HttpURLConnection connection = (HttpURLConnection)url.openConnection();
connection.setRequestMethod("GET");
connection.setRequestProperty("x-nxopen-api-key", API_KEY);
int responseCode = connection.getResponseCode();
BufferedReader in;
if(responseCode == 200) {
in = new BufferedReader(new InputStreamReader(connection.getInputStream()));
} else {
in = new BufferedReader(new InputStreamReader(connection.getErrorStream()));
}
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
} catch (Exception exception) {
System.out.println(exception);
}
}
}
JavaScript 샘플코드
const API_KEY = "YOUR API KEY HERE";
const characterName = "CHARACTER NAME";
const urlString = "https://open.api.nexon.com/heroes/v1/id?character_name=" + characterName;
const answer = fetch(urlString, {
headers:{
"x-nxopen-api-key": API_KEY
}
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error(error))
console.log(answer)
Python 샘플코드
headers = {
"x-nxopen-api-key": "YOUR API KEY HERE"
}
characterName = "CHARACTER NAME"
urlString = "https://open.api.nexon.com/heroes/v1/id?character_name=" + characterName
response = requests.get(urlString, headers = headers)
print(response.json())
애플리케이션 제작하기
Open API를 이용하여 이용약관에 명시되어 있는 사항 내에서 자유롭게 애플리케이션을 제작하실 수 있습니다만, 제작 시 데이터를 NEXON Open API에서 제공 받았음을 애플리케이션 내에 명시해주셔야 합니다.
NEXON Open API 표기
서비스 및 애플리케이션에 'Data based on NEXON Open API'라는 문구를 명시해주시길 바랍니다.