SKT는 open API 플랫폼에서 위치 기반 서비스 (TMAP, OVS), 지오비전 서비스 (지하철 혼잡도, 장소 혼잡도, 국내여행, 음식점), 인공지능 서비스(NUGU facecan, META) 등 다양한 오픈 API 서비스를 제공합니다. 한샘글로벌은 이 플랫폼에 적용될 아래 3가지 콘텐츠 제작 사업에 참여했습니다: 포털 페이지, 포털 이용 가이드, API 가이드
오픈 API란?
오픈 API는 웹사이트나 앱에서 이용자가 요청하면 외부 데이터를 가공해서 응답해주는 것을 말합니다. 앱 개발자들은 오픈 API를 통해 직접 개발하기 어려운 기능이나 데이터를 쉽게 앱에 추가할 수 있으며, 이는 개발 비용을 절감하고 앱 출시 시간을 단축하여 사용자들에게 더 빠르게 새로운 기능과 서비스를 제공할 수 있도록 합니다.
오픈 API 서비스를 제공하는 기업은 자사의 데이터를 다른 기업이나 개발자들과 공유하여 새로운 가치를 창출과 함께 브랜드 인지도도 향상할 수 있습니다. 사용자는 더욱 다양하고 유용한 앱을 경험하는 것은 물론입니다.
오픈 API를 이용한 앱 개발은 보통 요구사항 분석(목적과 기능 정의, 앱에 필요한 데이터 및 기능 제공하는 오픈 API 찾기), API 키 발급, 앱 개발, 테스트 및 배포 프로세스를 거칩니다. 오픈 API 웹 사이트는 앱 개발자가 앱 개발에 필요한 기능이나 데이터 등 정보를 찾고, 학습하고, 이용하는 아주 중요한 공간이기 때문에 오픈 API 서비스 제공 기업은 앱 개발자가 원하는 정보나 데이터에 쉽게 접근할 수 있도록 만들 필요가 있습니다.
open API 포털 페이지
화면 구성과 사용자 인터페이스 전반에 걸친 디자인 설계와 스타일은 고객사에서 구현 중에 있었기 때문에 한샘글로벌은 포털 페이지에 들어갈 텍스트 콘텐츠 제작을 전담했습니다. API 상품별 소개 페이지와 주요 섹션에 배치될 텍스트 정보를 작성하고 제안하는 작업이었습니다.
한샘글로벌은 포털 페이지에 수록될 텍스트 정보를 다음 3가지에 주안점을 두고 작업했습니다.
- API 포털 디자인의 컨셉과 맥을 같이하여, 서비스의 철학, 기술성, 미래상을 보여줄 것
- 사용자 경험을 고려하여 깔끔하고 직관적인 디자인으로 정보를 배치할 것
- 간결한 문장과 가독성 높은 이미지/아이콘으로 누구나 쉽게 정보를 찾고 이용할 수 있도록 할 것
API 상품 소개가 포털 페이지에 배치되므로 상품별 소개 페이지 콘텐츠를 작업하는 과정은 도전이었습니다. 다양한 API의 기술적 특성과 기능을 충분히 이해해야 하며, 이를 바탕으로 명확하고 정확한 설명을 작성해야 했습니다. 일관된 톤과 스타일을 유지하는 것도 중요했습니다. 회사의 브랜드 음성과 일치하는 글을 작성해야 하며, 이는 모든 문서에서 일관성있게 유지되어야 했습니다.
우리는 이 과정 동안 개발자들과 밀접하게 소통하며 협업과 반복적인 검토 과정을 통해 정보에 대해 정확하게 파악하고 글을 완성해 갈 수 있었습니다.
포털 이용 가이드
API 앱 개발자는 먼저 포털 회원 가입(계정 등록), API 키(인증 키, 앱 키) 생성, 상품 구독, 설정 및 관리 절차를 거쳐야 합니다. 우리는 이러한 일련의 절차를 소개하고 방법을 설명하는 포털 이용 가이드 제작을 진행했으며, 포털 이용 가이드는 다음 3가지에 주안점을 두었습니다.
- 회원 가입부터 상품 구독에 대해 이용자가 따라 하기만 하면 쉽게 완료할 수 있도록 할 것
- 포털의 사용자 계정과 open API 개발의 연관성을 쉽게 이해하고 이용할 수 있도록 할 것
- 지속적으로 사용자 프로필(계정)을 쉽게 유지 관리할 수 있도록 할 것
open API를 이용한 앱을 개발하기 전에 거쳐야 할 필수 절차와 관리 방법을 처음부터 끝까지 순차적으로 논리 정연하게 안내하여 이용자가 따라 하면서 작업을 완수하고 관리할 수 있도록 했습니다.
open API 가이드
open API를 이용한 앱 개발은 API 서비스를 제공하는 서버에 데이터를 호출(Request)하여 그 결과로 얻은 데이터(Response)를 처리하여 완성됩니다. 상품별 open API 가이드 제작은 다음에 주안점을 두고 작업했습니다.
- 개발에 필요한 정보를 찾아 헤매지 않고 한 페이지 내에서 모든 정보를 확인할 수 있을 것
- 단, 에러 코드와 같은 상품별 공통 사항은 별도 페이지에서 다루어 공통점이나 차이점이 비교되도록 하면서 동일 정보의 중복을 배제할 것
- 설명 구조와 형식을 SKT open API 포털에서 제공하는 모든 open API 상품에 일관되게 유지할 것. 사용자가 어느 API 가이드에 있더라도 원하는 정보가 어디쯤에 있을 거라 쉽게 예측하고 찾을 수 있도록 사용 편의성을 높였습니다.
개별 API 가이드 페이지 설명 구조
open API 가이드는 구독 상품의 API별로 API 호출 방법과 결과 데이터에 대한 설명까지 한 페이지 내에서 설명하여 개발자가 정보를 찾기 위해 여러 페이지로 이동하는 번거로움을 줄이고자 했습니다. 그래서 한 페이지 안에서 다음과 같은 정보로 구성했습니다.
- open API 명칭
- 메서드 및 엔드포인트
- 소개 및 설명
- 개발 예시 화면
- 유의 사항(제약 사항)
- 호출 예시
- 호출(Request) 파라미터 정보
- 호출 결과(Response) 파라미터 정보
- 예제 및 실행 결과 정보
상품별 공통 페이지
반면, API 실행 시 통신 실패에 대한 상황은 상품별로 거의 동일하기 때문에 동일한 내용을 개별 페이지에 중복해서 기술하기 보다는 별도의 페이지에서 설명했습니다. 공통 사항은 별도의 페이지에 두면 각 API별로 공통점과 차이점 비교가 용이합니다. 또한 라이터나 문서 관리자 입장에서도 중복성 배제는 정보 변경 시 1곳만 수정하면 되기 때문에 관리적인 면에서도 효율적입니다.
글을 마치며
이 프로젝트는 약 3개월에 걸쳐 open API 포털과 포털 이용 가이드 그리고 API 사용 가이드 제작으로 나누어 진행되었으며 사용자가 논리적으로 이해하기 쉽고 정확한 정보를 쉽게 찾아서 이용하고 학습할 수 있도록 하는 데 집중한 작업이었습니다. 이 기술은 테크니컬 라이팅에서 필요한 가장 기본적이며 가장 보편적으로 추구 하는 방향이기도 합니다.
이 작업은 교통, 인공지능, 지오비전 등 다양한 분야의 100여 개가 넘는 API 별 가이드를 제작하는 것이었기 때문에 가이드 정보 오류로 인해 앱 개발에 문제가 발생하지 않도록 고객사 API 개발 담당자와 적극적인 커뮤니케이션 (검증-피드백 반영)도 중요한 과제이기도 했습니다.
SK open API 포털은 정상적으로 오픈되었고 많은 개발자들이 접근하는 포털이 되었습니다. 그들이 open API를 활용하여 멋진 솔루션을 개발하길 기대해 봅니다.