API의 의미가 다양하게 쓰이고 있으며, 네이버 개발자센터에서 사용되고 있는 오픈 API 관련 개념들을 정확하게 정의함으로써 오픈 API를 처음 접하는 분들 또는 기존의 개발자분들이 헷갈리지 않도록 하기 위해 용어정리를 하였습니다.
운영체제, 시스템, 애플리케이션, 라이브러리 등을 개발자들이 프로그래밍 작업을 통해 응용 프로그램을 작성할 수 있는 다양한 인터페이스들을 총칭합니다. (예: Window API, Java API, HTML5 API, Android API…)
오픈 API는 API 중에서 플랫폼의 기능 또는 컨텐츠를 외부에서 쓸 수 있도록 웹 프로토콜(HTTP)로 호출할 수 있도록 개방(open)한 API를 의미합니다. 네이버 개발자센터에서 제공하고 있는 지도, 검색을 비롯 기계번역, 캡차, 단축 URL 등 대부분 API 들은 HTTP로 호출할 수 있는 오픈 API에 해당합니다.
애플리케이션은 API를 활용하여 만들어지는 다양한 프로그램 결과물입니다. 여기서는 개발자들이 네이버 오픈 API를 활용하여 만드는 웹, 모바일 웹, 모바일 앱 들을 지칭합니다. 네이버 오픈 API를 이용하려면 네이버 개발자센터의 ‘애플리케이션 등록’메뉴에 애플리케이션 정보를 등록하여야 이용하실 수 있습니다.
네이버 오픈 API는 대부분 https://openapi.naver.com/ 서버를 통하여 호출합니다. 이 서버가 바로 API 게이트웨이 서버이며, 오픈 API 호출이 들어오면 API 호출이 정확한지 판별하고, 인증된 사용자인지, 호출 허용량이 맞는지를 확인해서 실제 각 API 서버를 호출한 다음 결괏값을 리턴합니다. 만일 호출이 잘못되었을 경우는 에러 코드와 메시지를 리턴합니다.
이전 네이버 개발자센터에서 오픈 API를 이용하려면 각 API별로 ‘API키’라고 하는 유니크한 텍스트 문자열을 발급받고, 이를 API 호출시 같이 API 게이트웨이 서버로 전송함으로써 인증된 사용자임을 입증했습니다. 새로운 개발자센터에서는 API 키 방식은 더 이상 사용하지 않고 애플리케이션마다 일종의 유니크한 아이디와 비밀번호(클라이언트 아이디, 시크릿)값을 이용해서 인증하고 있습니다.
오픈 API 사용자가 인증된 사용자인지를 확인하는 수단으로 네이버 개발자센터의 ‘애플리케이션 등록’메뉴에서 애플리케이션을 등록하면 발급되는 일종의 유니크한 아이디와 비밀번호 값으로 각기 클라이언트 아이디와 클라이언트 시크릿이라고 합니다. ‘애플리케이션 등록 및 클라이언트 아이디와 시크릿 가이드’
오픈 API를 호출하기 위한 API의 웹 주소(URL)을 의미합니다. 이전 네이버 개발자센터의 오픈 API들은 http://openapi.naver.com이었지만, 현재는 대부분 https://openapi.naver.com/버전/서비스구분/API 구분 형태로 구성되어 있습니다.
오픈 API를 호출할 때 함께 서버로 전송해야 하는 값들로서, 각 API 명세를 참조하여 요청 변수명이 틀리거나 필수 요청변수가 빠지지 않도록 주의하셔야 합니다.
한글이나 특수문자가 요청 변수값에 포함되어 있을 경우 서버 전송 시 값이 깨지기 때문에 지정된 규칙에 따라 문자값을 코드값으로 변환해서 전송해야 하며 이를 URL 인코딩이라 합니다. URL 인코딩된 값을 다시 원래의 값으로 변환하는 것을 URL 디코딩이라고 합니다.
HTTP 프로토콜에서 웹서버가 요청과 응답 데이터를 전송할 때 사전에 약속된 동작 방식으로 W3C에서는 GET, POST를 비롯 8가지의 메서드가 정의되어 있습니다. 네이버 오픈 API를 호출하기 위해 서버로 요청을 보낼 때 반드시 API 명세이 지정된 메서드에 따라 API를 호출해야 합니다.
HTTP 헤더는 웹서버로 보내는 요청과 요청 데이터를 설명하는 메타 정보들이 들어있습니다. 즉 메서드가 무엇인지, 요청 URL이 무엇인지, http 프로토콜 버전 등이며, 여기에 추가적으로 지정된 이름과 값을 전송할 수 있습니다. 네이버 오픈 API는 기본적으로 클라이언트 아이디와 시크릿값을 헤더에 포함하여 전송해야 이용할 수 있도록 되어 있습니다.
서버로 API 요청을 보내면 서버에서는 API 호출이 잘되었는지 HTTP 상태코드 값과 함께 응답을 보냅니다. 이를 테면 호출이 정상적으로 이뤄졌을 경우는 200, API 호출 방법이 잘못되어 에러가 났을 경우에는 400, 403, 404, 서버 오류가 있을 때는 500과 같은 상태코드를 리턴합니다. 네이버 오픈 API 에러 코드를 참조하시기 바랍니다.
인증이라함은 어떤 사용자가 본인임을 식별하는 것으로 일반적으로 아이디와 암호가 일치하는 것으로 판단합니다. 네이버에 로그인할 때 네이버 사용자가 네이버 아이디와 암호를 입력해서 로그인하는 것이라 생각하시면 되겠습니다. 그러나 제삼자가 네이버 오픈 API를 이용해서 만든 애플리케이션에 사용자가 네이버 아이디와 암호를 직접 입력할 경우는 보안이슈가 있습니다. 그래서 이럴 경우는 제삼자가 만든 애플리케이션이 아니라 네이버의 아이디와 암호를 입력받는 서비스를 이용해서 인증을 하고, 인증성공/실패 여부를 애플리케이션에 전달하게 하면 이용자는 안심하고 사용할 수 있습니다. 이러한 절차를 정의한 오픈 스탠다드가 바로 OAuth이며, 네이버 오픈 API 에서는 버전 2.0으로 인증을 서비스하고 있습니다.
OAuth 2.0으로 인증에 성공하면 네이버 플랫폼에서는 접근 토큰(access token)이라는 복잡한 문자열값을 애플리케이션에 전달합니다. 이 값은 로그인 오픈 API를 호출할 때 사용합니다. 네이버 오픈 API 중에서 회원 프로필 조회, 블로그 글쓰기, 카페 가입과 같은 API들은 회원 인증이 되어야만 호출 가능한 로그인 오픈 API들입니다. 이런 오픈 API들을 호출할 때는 요청 헤더에 접근 토큰 (access token)값을 함께 보내주어야 호출이 가능합니다.