Open API 플랫폼 & 비전공자가 API를 마주하는 방법_코드스테이츠 PMB 11기| W7D3

오늘의 학습 내용은 바로 API! 귀에 거슬릴 정도로 많이 들었지만 그다지 친숙하지는 못한... 과거 학부 시절에 수업 내용 실습을 위해 API를 이용해 본 적 있었지만 기억에 남는 건 없다. 사실 그 개념이 뭔지도 모르고 그냥 시키는 대로 따라 했던 것에 가까운 것 같다.
그런 의미에서 오늘의 학습 내용은 나름 유익했다. 뭔가의 기능!이라고 생각했던 API에 대해서 알게 되었고, 어떤 방식으로 작동하는지도 과제를 수행하며 알게 되었다:)

API란,

내가 이해한 것을 바탕으로 API를 설명하자면, '출입국 심사서'와 같은 느낌이다. 입국할 때 출입국 신고서를 작성하고 입국 승인을 받듯, 컴퓨터의 세계에서도 비슷한 방식으로 기능이 작동하는 듯하다. 서버에서 미리 정해놓은 양식(API, 출입국 신고서)을 공개하고, 이 기능/데이터를 원하는 개발자(Client)가 양식의 빈칸을 채워(데이터) 서버에게 요청한다. 해당 API가 필수적으로 요구하는 사항들이 정상적으로 담겨있다면 서버는 클라이언트에게 원하는 기능/데이터를 제공한다.

이러한 이해를 바탕으로 오늘 수행할 과제는 Open API 플랫폼과 API를 뜯어보는 것이다. 오늘의 product(?)는 바로 네이버 개발자 센터. product인 듯 product 아닌 그런... 오묘한 느낌이지만, Open API 플랫폼에 대해 알아보고, 네이버 개발자 센터를 중심으로 API를 살펴봤다!

---

미리 덧붙이자면, 내가 조사하고 정리한 Open API 플랫폼은 국내에 한정했다. 물론 인터넷으로 글로벌하게 연결되는 시대이지만, 일단 내 한계로는... 국내도 버겁기 때문에^^... 나름 가까이 있는 것부터 알아보고자! 국내로 범위를 한정 지어 과제를 수행했다는 점을 미리 밝힌다:)

Open API 플랫폼

네이버 개발자 센터 | 대기업

국내 인터넷 검색엔진 시장 점유율의 약 60%를 차지하고 있는 네이버는 다양한 API 서비스를 제공하고 있다. 기초적인 검색, 로그인, 공유하기 기능부터 네이버 클로바의 인공지능, 머신러닝, 파파고 등의 상위 기술까지 폭넓은 범위의 API를 보유하고 있다. 최근에는 네이버 개발자 센터를 넘어 네이버 클라우드 플랫폼으로 일부 API 사업을 옮겨 운용하는 것으로 보아, 이전보다 더욱 고도화된 서비스를 제공할 것으로 보인다.
메인 화면에는 5개의 대분류가 아이콘과 함께 노출되어 있으며, 하단에는 API 사용과 관련한 최근 공지사항을 보여준다. API의 경우 타 서비스 내부에서 운용되는 경우가 많기 때문에 이에 대한 변경 사항을 눈에 띄게 배치한 것이라 생각한다.
일부 API의 경우 사용 유무나 운용량에 따라서 과금 정책을 실시하고 있지만, 대부분의 API는 Open API의 일종으로 무료로 제공하고 있는 모습을 확인할 수 있었다. 이러한 맥락으로 '판매'보다는 '공유'의 느낌이 다분했으며, 공공의 성격을 나타내는 것으로 받아들여지기도 한다.

Kakao developers | 대기업

메신저 서비스로 시작한 카카오는, 더 이상 국내에서 '메신저'로만 남아있지 않다. 네이버에 대적할 만큼 덩치를 가졌으며, 모바일에 최적화된 서비스를 제공하기 때문에 관련 기술을 많이 확보하고 있다. 전체적인 구성(제품/문서/도구/포럼 등)은 네이버와 크게 다르지 않으며, 상단에서 언어를 선택할 수 있다는 것이 약간의 특이점으로 보인다. (개발 언어가 영어로 이루어져 있기 때문에, 개발자들이 영어에 익숙해서 그럴까? 내 추측이다)

카카오의 경우 네이버와는 약간 다른 분위기를 엿볼 수 있었는데, 자주 사용되는 API들을 메인 화면에 직접 노출시킨 것이다. 카카오싱크(간편 가입), 카카오 로그인, 메시지(공유), 지도 등 개발자들이 많이 사용하는 API들을 메인에 노출시켰으며, 네이버와 비슷한 API를 제공하면서도 독특한 분위기를 자아냈다. API를 "제품"이라 표현한 부분이 신선했는데, 네이버에 비교해 본격적으로 비즈니스의 느낌이 났으며, 기능별 제품 소개와 문서가 각각 배치되어 있다.
하단에는 [카카오 API의 특징]과 [공지사항], [관련 소식] 콘텐츠가 위치했는데, [공지사항]의 경우 텍스트 리스트로 3개만이 노출되어 있었다. 네이버 개발자 센터에 비해 '판매성'이 더욱 느껴졌으며, 개발자들도 일종의 비즈니스라 생각한다면 API 플랫폼인데도 B2B의 느낌이 강했다.

공공 데이터 포털 | 공공

언뜻 보면 구글과 비슷한 UI를 가진 공공데이터 포털은, 국가에서 운영하는 데이터 플랫폼이다. API를 비롯해 다양한 데이터 셋을 다운로드할 수 있으며, 다양한 주제에 대한 데이터를 다룰 수 있다는 특징이 있다. 국가에서 운영하기 때문에 무료로 운영되며, 회원가입 후 API를 연결해 사용할 수 있다.

국가에서 운영하는 서비스답게(?) 네이버와 카카오와는 전혀 다른 분위기를 나타냈다. 앞선 두 기업의 API는 '기능'으로서의 성격이 강했다면, 공공 데이터 포털의 경우 이름처럼 "데이터"의 성격이 강하다. 다양한 주제의 데이터를 다루는 만큼 원하는 API나 데이터 셋을 찾기 쉽도록 '검색' 기능이 강화되어 있으며, 원하는 데이터가 없을 시에는 이를 직접 국가에 요청할 수도 있다. [인기 데이터]를 통해 최근 사람들이 많이 관심 가지는 주제들을 엿볼 수 있으며, [최신 데이터]를 통해 가장 신선한(?) 데이터를 접할 수도 있다.
공공데이터 포털은 "행정안전부"에서 관리하는 플랫폼으로 지방행정 단위부터 국가 단위의 데이터까지 폭넓은 범위의 Open API를 제공하고 있다. 글을 작성하는 2022년 04월 27일 기준으로 8,977건의 Open API가 등록되어 있으며, (내 경험을 바탕으로) 간단한 회원가입 후 활용 목적을 간단히 입력하면 자동으로 승인되어 API 이용이 자유로웠다. 기능이 아닌 데이터라 그런지 복잡한 코드 없이 단지 API를 호출하는 코드만 있다면, 바로 API를 사용할 수 있었다. (처음 데이터 사용 신청을 하면, 최대 24시간 정도 딜레이가 되기도 한다. API를 불러오는 시간이 아닌, 승인을 인식하는? 시간이라 보면 될 것 같다.)

통계지리정보서비스 (SGIS) | 공공

국가에서 운영하는 또 다른 데이터 서비스인 '통계지리정보서비스(SGIS)'는 #통계와 #지리를 중심으로 다양한 주제에 대한 데이터를 다룬다. 사이트 내에서 시각화도 잘 되어 있으며, 국내 지역별 통계 데이터를 가시적으로 제공한다. 이 또한 데이터셋, 혹은 Open API로 이용할 수 있으며, 앞선 공공데이터 포털처럼 '기능'보다 '데이터'의 성격이 매우 강하다.
SGIS의 경우 행정안전부가 아닌 "통계청"에서 관리하는 플랫폼으로, (당연한 얘기겠지만) 공공데이터 포털보다 통계적 성격이 강함을 느낄 수 있었다. 또한 공공데이터 포털과는 달리 시각화 자료를 잘 제공하고 있어, 이와 관련된 데이터 파악 및 API 사용에 유리해 보이는 느낌이다.

✅ 정리

• Open API는 기업, 혹은 국가 단위로 운영되는 플랫폼을 통해 이용할 수 있다.
• API의 출력값은 크게 '기능'과 '데이터'로 구분할 수 있으며, 양쪽의 성격을 모두 띌 수 있다.
• 대체로 공공기관에서 제공하는 Open API는 특정 기능보다 "정보(데이터)"에 치중된 경향이 강하다.
• 일반 기업에서 제공하는 Open API의 경우 '기능'의 성격이 강하기 때문에 변동사항이 발생할 가능성이 높다. (따라서 공지사항을 주시해야 함)

---

🔍 네이버 개발자 센터의 API 살펴보기

학부 시절 실습(?)을 위해 API를 사용해 본 경험이 있다. 별 것 아니었지만, 이 순간에는 매우 유용하게 느껴진다. API를 자세히 뜯어보는 실험체로는 "네이버 개발자 센터"를 선택했다. 국내에서 가장 큰 포털이기도 하고, 과거 사용한 경험이 있기에 그나마 친숙하기 때문이다.
(공공데이터 포털의 경우도 사용해 본 적이 있지만, PMB 과정에는 데이터보다 '기능'의 성격에 초점을 맞추는 것이 좋을 것 같아 네이버를 선택했다.)

네이버 API 요약

네이버 API의 IA(?)

네이버의 Open API는 (말 그대로 Open API이기에) 비로그인 Open API, 그리고 REST API 형식을 채택하고 있다. HTTP 프로토콜을 사용하기에 http의 method, 즉 GET, POST, PUT, DELETE를 사용하며, 주로 데이터를 출력하는 기능의 API를 제공하고 있다. HTTP Request Message의 Header 부분의 url에 데이터를 담아서 API를 요청하는 형태로 작동되며, 개발자 센터에서 오픈 API 사용 등록을 통해 발급받은 Client ID와 Secret으로 API를 이용할 수 있다.

네이버 개발자 센터

네이버 개발자 센터

네이버 개발자 센터는 국내 대표 포털답게 많은 API를 제공하고 있다. 크게 CLOVA, 네이버 로그인, 파파고, 서비스 API로 나뉘며, 하위에 수많은 기능들의 API가 존재한다. 내 경험상 예전에는 '네이버 개발자 센터'에서 모든 API를 관리했던 것 같은데, 최근에는 몇몇 API는 네이버 클라우드 플랫폼을 이용해야 한다는 배너와 안내가 종종 보인다. 네이버 클라우드를 강화하는 전략이어서 그런지, 기술상의 문제인지는 몰라도 고도화된 수준의 API를 별도로 관리하는 듯한 느낌이 들었다.

(좌) 네이버 개발자 센터의 햄버거 메뉴 / (우) 서비스 API > 검색 페이지

이 중 좀 더 자세히 살펴본 부분은 서비스 API 영역이다. 아마 대부분의 서비스들이 가장 많이 이용하는 API가 소속되어 있으며, 하위에 데이터랩 / 검색 / 단축 URL / 캡차 / 네이버 공유하기 /모바일앱 연동 / 네이버 오픈 메인으로 중분류 카테고라이징 되어 있다. [검색]을 살펴보면 해당 기능에 대한 설명이 나와있고, <오픈 API 이용 신청>과 <개발 가이드 보기> CTA가 나와있다.

(좌) 검색 API에 대한 다양한 소분류 / (우) 개발 가이드 문서

<개발 가이드 보기>로 들어가면 [Documents > 서비스 API > 검색] 경로로 이동한 페이지가 보이며, [검색]도 다양한 소분류로 나뉜다. 블로그, 뉴스, 책 등 여러 카테고리 별로 다른 검색 API 코드가 존재하며, 이러한 검색 API를 이용하기 위해 준비 과정이 필요하다. <개발 가이드>에는 가장 먼저 (0) API 호출에 대해 각 프로그래밍 언어별 예제가 나와있고, 뒤이어 (1) API 사용을 위한 준비사항이 안내되어 있다. (2) API의 기본 정보(XML, JSON)와 (3) 요청 변수, (4) 출력 결과, (5) 에러 코드 등도 함께 보여준다. 마지막으로 API가 작동했을 때의 (6) 예시(호출, 요청, 응답) 코드를 안내하며 <개발 가이드>가 끝난다. 이를 통해 개발자들은 네이버의 검색 API를 이용하기 위한 기본적인 코드 빌드업이 가능하며, 이를 바탕으로 각 서비스들에 맞게 적용하여 네이버의 API를 사용할 수 있다. 또한 각자의 product에 API를 적용했을 때 정상적으로 작동하는지도 코드를 통해 확인할 수 있어 개발자들에게 큰 가이드라인을 제공하고 있다.

🚨 한계

Open API를 이용하면 원하는 기능과 수많은 데이터를 손쉽게 product에 적용할 수 있다는 이점이 있다. 다만, 네이버 개발자 센터에서 제공하는 Open API의 대부분은 '기능'에 관련된 것이기 때문에 주기적으로 관련 공지를 확인해야 한다. 또한 출력값 역시 네이버의 서버를 이용하기에, Open API를 이용하는 것은 해당 플랫폼에 일부 종속되어 있다 볼 수 있어 독립성이 떨어질 수 있다. (해당 기능에 대해 플랫폼에 의존해야 한다.)
또한 이미 만들어진 API이기에 개발자들이 임의로 이를 변경해서 적용하는데 한계가 있다. (즉, 어쩔 수 없이 해당 기능/데이터를 그대로 갖다 써야 한다.) 프론트엔드를 손본다 하더라도 product의 개성을 침해받을 수 있기에, 주어진 리소스와 개발 난이도, product의 특성 등을 고려하여 Open API를 이용해야 한다.

🔍 이미지 검색 API 들여다보기

위에서 설명한 "네이버 개발자 센터"에서 제공하는 기능 API 중 '이미지 검색 API'를 자세히 들여다보자. 이미지 검색 API는 검색 결과에 네이버 포털에서 제공하는 이미지 검색 결과를 출력해 주는 API이다. <개발 가이드>에 따르면 '이미지 검색 API'는 REST API 형식을 취하고 있으며, 비로그인 Open API이므로 GET 호출 시 네이버 개발자 센터에서 API 사용 신청 시 발급받은 Client ID와 Client Secret 값을 전송하면 API를 사용할 수 있다.
보다 자세히 설명하자면, REST API는 http 프로토콜을 사용해 서버에 무언가를 요청한다. 이때 GET으로 요청하는데, 이때 요청하는 데이터가 HTTP Request Message의 Header 부분의 url에 담겨 전송된다. 네이버에서 제공해 준 호출 코드를 예시로 살펴보자. (사실 이 말을 보고 이해하지 못해도 좋다. 아래의 설명에서 계속!)

curl "https://openapi.naver.com/v1/search/image.xml?query=%EC%A3%BC%EC%8B%9D&display=10&start=1&sort=sim" \
    -H "X-Naver-Client-Id: {애플리케이션 등록 시 발급받은 client id 값}" \
    -H "X-Naver-Client-Secret: {애플리케이션 등록 시 발급받은 client secret 값}" -v

위의 코드에서 url을 제외한 2, 3번째 줄을 보자. 개발자들이 그들의 product에서 API를 사용하기 위해서는 <이용 신청>이란 절차를 거쳐야 한다. (그냥 코드만 친다고 되는 것이 아님!) 출생신고를 하면 주민등록번호를 부여받듯, 네이버 개발자 센터에서 오픈 API 이용 신청을 하면 Client ID와 Client Secret(비밀번호)를 부여받는다. 개발자들은 각자의 product에 API 코드를 작성할 때, 이때 부여받은 ID와 Secret을 입력해서 API를 호출하면 네이버의 서버에서 이를 인식하고 요청한 데이터를 보내준다. (이 부분은 이미지 검색 API만이 아닌, 타 API에서도 일반적으로 적용되는 방식이다) 위의 코드가 http의 header 부분에서 작동해야 API를 호출해 올 수 있다는 의미이다.

다음으로 살펴볼 것은 API의 기본 정보이다. 위의 코드에서 URL의 마지막 부분을 image.xml로 요청하면 xml 형태가, 그냥 image로 요청하면 json 형식으로 출력된다는 것을 의미한다. 앞선 예시로 나왔던 코드에서는 image.xml로 작성되어 있는 것을 보아 API가 xml 형태로 출력될 것임을 알 수 있다.

다음으로 살펴볼 부분은 API에서 요청하는 변수(데이터)이다. 클라이언트가 서버에 API를 요청할 때 데이터가 동반되는데, 이때 포함되어야 할 내용이라 생각하면 편할 것 같다. 몇 가지 변수만 살펴보자면 query는 이미지 검색 결과에 필수적으로 요구되는 변수로, string(문자열)로 작성되어야 한다. query 데이터는 UTF-8(한글)로 인코딩(적용)되어야 한다고 이해하면 된다.
다음 변수인 display는 integer(상수) 타입의 변수로, 기본 10, 최대 100의 값을 갖는다. 이는 API 호출 후 결과를 출력할 때 노출할 결과 건수를 지정하는 것이다. 코드에도 포함되지만, 일반적인 주소창(url)에서도 해당 변수를 발견한다면 숫자를 조정해 보자. 그렇다면 필터 CTA 조작 없이 원하는 개수의 검색 결과를 볼 수 있다:)! (대부분 유사한 변수명을 사용하기 때문. 물론 URL 마다 다를 수 있으니 주의)
그 외 요소들은 아마 개발자들이 유용하게 쓸 변수들...ㅎ 코드에 기본값으로 설정되도록 작성하여 product에 API를 호출할 것으로 예상된다.

출력 결과에 나타나는 변수(?)에 대한 안내이다. 해당 부분은 정말! 개발자들을 위한 부분으로.. PMB 과정이니까 괜찮아!라는 마음으로 합리화하고 넘어가기...ㅎ 그래도 변수들의 타입이나 설명들은 대체적으로 이해 가능하니, 가끔 코드를 볼 때 만나면 반가울 것 같다.
Client ID와 Secret, 그리고 요청 변수에 대해 정상적인 값을 담아 API를 요청했다면, 개발자들에게는 위의 출력 결과 코드가 보일 것이고, 이는 프론트엔드를 통해 유저들에게 이미지 검색 결과를 출력해 줄 것이다.

✅ 정리 및 결론

• 네이버 개발자 센터에서 운영하는 Open API는 REST API 형식을 가지며, 비로그인 Open API이다.
• 따라서 GET method를 통해 API를 요청할 때, htttp Request Message의 header의 url 부분에 데이터가 포함되어야 한다.
• 이때 오픈 API 사용 요청 시 발급받은 Client ID와 Client Secret이 필요하다.
• url 부분에 들어가는 데이터는 '요청변수'에 대한 데이터로 볼 수 있으며, 필수 요청 변수를 반드시 포함하고 주어진 범위 내의 값을 입력해야 한다.
• 이미지 검색 Open API의 경우 xml이나 json 형식으로 출력되며, 출력 결과의 필드값을 해석하여 API가 정상작동 했는지 알 수 있다.

---

오늘의 과제는 학습 내용과 어디서 주워 들었던 내용, 과거의 학부 수업을 더듬어가며 작성해서 부정확한 내용이 있을지도 모른다. 다만 나름... 서치도 해 가며 정확성을 더하고자 노력했다:) 이번 과제를 통해 과거 API를 사용했던 경험이 새록새록 떠오르며...🌟 나는 개발자를 못 할 것 같다는 생각이 더 단단해졌다! (PM으로 충분해?)
API는 기존에 있는 데이터나 기능을 효과적으로 가져올 수 있는 기능으로써 나중에 PM이 되어 서비스를 만들 때 유용하게 쓰일 것 같다. 다만 자세한 개발적인 내용까지 알기에는 무리가 있기에...ㅜ 좋은 개발자를 만나 잘 논의할 수 있길 바라며 오늘 과제를 마무리한다:) 얼렁뚱땅 마무리지만 어쩔 수 없다. 이미 뇌는 과부하! 그만그만!

fin.