NAVER API HUB 이관 가이드

Classic/VPC 환경에서 이용 가능합니다.

이 가이드는 기존 NAVER Developers Center에서 제공하던 API를 NAVER API HUB로 이관하여 사용할 때 확인해야 하는 항목과 변경해야 하는 연동 정보를 안내합니다.

기존 API와 동일한 기능을 NAVER API HUB에서 사용하려면 네이버 클라우드 플랫폼 계정으로 서비스 이용을 신청하고, 신규 Application을 등록한 후 발급된 인증 정보와 API 호출 주소를 서비스 코드에 반영해야 합니다.

이관 절차

NAVER Developers Center에서 사용하던 API를 NAVER API HUB로 이관하는 절차는 다음과 같습니다.

이관 전후 비교 및 기존 연동 정보 확인: 기존 NAVER Developers Center와 NAVER API HUB의 이용 방식 차이를 확인하고, 기존 서비스 코드에서 사용 중인 API 호출 주소, HTTP Method, 요청 헤더, 요청 파라미터를 확인합니다.
NAVER API HUB 이용 신청 및 Application 등록: 네이버 클라우드 플랫폼 콘솔에서 NAVER API HUB 이용을 신청하고 API 호출에 사용할 Application을 등록합니다.
인증 정보 확인 및 변경: NAVER API HUB에서 발급된 Client ID와 Client Secret을 확인하고, 기존 인증 정보를 신규 인증 정보로 교체합니다.
API 호출 정보 변경 및 동작 확인: API 호출 주소와 요청 헤더를 NAVER API HUB 기준으로 변경한 후 정상 호출 여부를 확인합니다.
오류 처리 확인: 인증 실패, 권한 없음, 필수 파라미터 누락 등 실패 상황에서 반환되는 오류 응답을 확인하고, 기존 서비스의 예외 처리 로직이 정상적으로 동작하는지 확인합니다.

이관을 시작하기 전 기존 서비스 코드에서 다음 항목을 확인해 주십시오.

확인 항목	설명
사용 API	기존 서비스에서 사용 중인 API <예시> 검색 API, 데이터랩 API 등
호출 주소	서비스 코드에서 호출 중인 API 엔드포인트를 확인합니다.
HTTP Method	GET 또는 POST 등 API 호출 방식을 확인합니다.
요청 헤더	기존 인증 헤더와 인증 정보 사용 방식을 확인합니다.
요청 파라미터	API 호출 시 전달하는 Query String 또는 Request Body 항목을 확인합니다.

1. 이관 전후 비교 및 기존 연동 정보 확인

NAVER Developers Center에서 NAVER API HUB로 이관할 때 확인할 수 있는 주요 화면은 다음과 같습니다.

화면 예시	기존 NAVER Developers Center	NAVER API HUB
서비스 이용 신청	-
API 선택 및 Application 등록
Application 정보 입력
인증 정보 확인
API 호출 결과 확인

2. NAVER API HUB 이용 신청 및 Application 등록

NAVER API HUB를 사용하려면 네이버 클라우드 플랫폼 콘솔에서 서비스 이용을 신청하고, API 호출에 사용할 Application을 등록해야 합니다.

이용 신청 및 Application 등록 절차는 다음과 같습니다.

네이버 클라우드 플랫폼 콘솔에 접속해 주십시오.
Menu > Services > Application Services > NAVER API HUB > 신청하기 메뉴를 차례대로 클릭해 주십시오.
Subscription 메뉴에서 [서비스 이용 신청] 버튼을 클릭해 주십시오.
이용 약관 및 개인정보 제공 안내를 확인한 후 이용 신청을 완료해 주십시오.
Application 메뉴에서 [Application 등록] 버튼을 클릭해 주십시오.
사용할 API를 선택한 후 [다음] 버튼을 클릭해 주십시오.
Application 이름을 입력한 후 등록을 완료해 주십시오.

참고

NAVER API HUB에서는 하나의 Application에 여러 API를 등록할 수 있습니다.
다만 API별 호출 주소와 요청 파라미터는 다르므로, 서비스 코드에서는 API별 호출 로직을 분리하여 구현해야 합니다.

3. 인증 정보 확인 및 변경

Application 등록을 완료하면 API 호출에 필요한 인증 정보가 생성됩니다.

기존 NAVER Developers Center에서 사용하던 인증 정보는 NAVER API HUB 호출에 사용할 수 없으므로, NAVER API HUB에서 신규 발급된 Client ID와 Client Secret을 서비스 코드에 반영해야 합니다.

인증 정보 변경 시 확인해야 하는 항목은 다음과 같습니다.

변경 항목	NAVER Developers Center	NAVER API HUB	변경 내용
Client ID	기존 Application의 Client ID	NAVER API HUB Application의 Client ID	새로 발급된 Client ID로 교체
Client Secret	기존 Application의 Client Secret	NAVER API HUB Application의 Client Secret	새로 발급된 Client Secret으로 교체
Client ID 요청 헤더	`X-Naver-Client-Id`	`X-NCP-APIGW-API-KEY-ID`	요청 헤더명을 NAVER API HUB 기준으로 변경
Client Secret 요청 헤더	`X-Naver-Client-Secret`	`X-NCP-APIGW-API-KEY`	요청 헤더명을 NAVER API HUB 기준으로 변경
인증 정보 적용 위치	서비스 코드 또는 환경 변수	서비스 코드 또는 환경 변수	기존 인증 정보 사용 위치 확인 후 신규 인증 정보로 변경

인증 정보 확인 절차는 다음과 같습니다.

NAVER API HUB 메뉴에서 Application을 클릭해 주십시오.
Application Management 화면에서 등록한 Application을 선택해 주십시오.
[인증 정보] 버튼을 클릭해 주십시오.
Client ID와 Client Secret을 확인해 주십시오.
확인한 값을 서비스 코드 또는 환경 변수에 반영해 주십시오.

다음 이미지는 NAVER API HUB에서 인증 정보를 확인하는 화면 예시입니다.

NAVER API HUB 인증 정보 화면

주의

기존 NAVER Developers Center에서 사용하던 Client ID와 Client Secret은 NAVER API HUB 호출에 사용할 수 없습니다.

4. API 호출 정보 변경 및 동작 확인

인증 정보를 확인한 후 기존 서비스 코드의 API 호출 주소와 요청 헤더를 NAVER API HUB 기준으로 변경합니다.

API 호출 정보 변경 시에는 호출 주소, 요청 헤더, 요청 파라미터, 정상 응답 형식을 함께 확인해야 합니다.

호출 정보 변경 예시

확인 항목	NAVER Developers Center	NAVER API HUB	변경 내용
호출 도메인	`https://openapi.naver.com`	`https://naverapihub.apigw.ntruss.com`	NAVER API HUB 호출 도메인으로 변경합니다.
API Path	`/v1/search/news.json`	`/search/v1/news`	NAVER API HUB 개발 가이드에 명시된 API Path로 변경합니다.
HTTP Method	`GET`	`GET`	API별 개발 가이드 기준으로 확인합니다.
Query String	`query={QUERY}&display=5`	`query={QUERY}&display=5`	API 개발 가이드와 실제 호출 결과를 기준으로 동일하게 사용할 수 있는지 확인합니다.
Client ID 헤더	`X-Naver-Client-Id`	`X-NCP-APIGW-API-KEY-ID`	NAVER API HUB 인증 헤더명으로 변경합니다.
Client Secret 헤더	`X-Naver-Client-Secret`	`X-NCP-APIGW-API-KEY`	NAVER API HUB 인증 헤더명으로 변경합니다.

변경 전후 호출 예시는 다음과 같습니다.

# NAVER Developers Center
curl -X GET "https://openapi.naver.com/v1/search/news.json?query={QUERY}&display=5" \
  -H "X-Naver-Client-Id: {DEVELOPERS_CLIENT_ID}" \
  -H "X-Naver-Client-Secret: {DEVELOPERS_CLIENT_SECRET}"

# NAVER API HUB
curl -X GET "https://naverapihub.apigw.ntruss.com/search/v1/news?query={QUERY}&display=5" \
  -H "X-NCP-APIGW-API-KEY-ID: {API_HUB_CLIENT_ID}" \
  -H "X-NCP-APIGW-API-KEY: {API_HUB_CLIENT_SECRET}"

참고

위 예시는 뉴스 검색 API 기준입니다.
API별 호출 주소, HTTP Method, 요청 파라미터는 각 API 개발 가이드를 참조해 주십시오.

동작 확인

API 호출 정보를 변경한 후 정상 응답이 반환되는지 확인합니다. HTTP 상태 코드, 응답 형식, 서비스 코드에서 사용하는 주요 응답 필드를 중심으로 확인해 주십시오.

확인 항목	변경 여부	확인 내용
HTTP 상태 코드	정상 호출 기준 변경 없음	정상 호출 시 `200 OK`가 반환되는지 확인합니다.
응답 Body 구조	API별 확인 필요	기존 서비스 코드에서 사용하던 주요 응답 필드가 동일하게 반환되는지 확인합니다.
주요 응답 필드	API별 확인 필요	예: `items`, `title`, `link`, `description` 등 서비스 코드에서 사용하는 필드를 확인합니다.
응답 파싱 로직	API별 확인 필요	기존 응답 파싱 로직을 그대로 사용할 수 있는지 확인합니다.
응답 Header	변경 가능	API Gateway 관련 응답 헤더가 추가되거나 변경될 수 있습니다. 서비스 코드에서 응답 헤더를 사용하는 경우 확인이 필요합니다.

참고

응답 구조는 API별로 다를 수 있으므로 실제 호출 결과와 API 개발 가이드를 기준으로 확인해 주십시오.
특히 서비스 코드에서 특정 응답 필드나 오류 코드를 기준으로 분기 처리하고 있다면, 이관 후 동일하게 동작하는지 별도로 확인해야 합니다.

5. 오류 처리 확인

이관 후 기존 서비스의 예외 처리 로직이 정상적으로 동작하는지 확인하려면 API 호출 실패 상황에서 반환되는 오류 응답을 확인해 주십시오.

확인할 수 있는 오류 케이스는 다음과 같습니다.

오류 케이스	확인 내용
인증 헤더 누락	인증 헤더 없이 호출했을 때 반환되는 오류 응답을 확인합니다.
잘못된 인증 정보	유효하지 않은 Client ID 또는 Client Secret을 전달했을 때 반환되는 오류 응답을 확인합니다.
잘못된 호출 주소	존재하지 않는 API Path로 호출했을 때 반환되는 오류 응답을 확인합니다.
필수 파라미터 누락	필수 요청 파라미터를 누락했을 때 반환되는 오류 응답을 확인합니다.
지원하지 않는 API 호출	제공되지 않는 API를 호출했을 때 반환되는 오류 응답을 확인합니다.

주의

NAVER API HUB는 API Gateway 기반으로 제공되므로 기존 NAVER Developers Center와 오류 응답 형식 또는 상태 코드가 다를 수 있습니다.
기존 서비스에서 오류 코드 기반 분기 처리를 하고 있다면 이관 후 오류 응답을 별도로 확인해 주십시오.

Documentation Index