brunch

매거진 공대생 기획자의 PM 이야기

라이킷 26 댓글

You can make anything
by writing

C.S.Lewis

계정을 잊어버리셨나요?

by 류니 Mar 06. 2022

PM은 API를 어디까지 다뤄야 할까?

[코드스테이츠 PMB 8]API, REST API, RESTful API

서버에서 이미지 URL을 보내줘야 하는데 'API'가 미완성인 것 같아요.

우리는 개발자와 소통하다 이런 이야기를 듣게 된다. 서버? URL? API? 이게 다 무슨 말일까?

API(Application Programming Interface) '애플리케이션'을 '프로그래밍'하는데 필요한 '인터페이스'이다. 인터페이스라는 것은 상호 간의 정보를 소통하기 위해 돕는 시스템을 뜻한다.

예를 들면 나는 돈을 찾기 위해서 은행에 간다. 이때 내가 은행 금고에 가서 바로 돈을 빼올 수 있는 것이 아니기 때문에 은행 창구로 가게 된다. 이때 은행 창구처럼 고객과 은행 사이에서 업무를 처리하는 역할과 유사한 개념이다. 은행은 고객이 돈을 빼기 위해서 보내는 사람 계좌번호, 상대방 계좌번호, 신분증 등 일련의 필요한 규칙들을 정해두었다. 고객과 은행이 서로 정보를 어떻게 주고받을지 형식을 정해둔 것이다. IT 서비스 내에서도 이렇게 상호 간에 정보 소통을 하기 위해서 API의 형태를 이용해 어떻게 정보를 주고받을지 정해두었다.

by. 류니

클라이언트가 '비디오 파일 줘'라고 서버에게 요청하면 API는 '비디오 파일 보내주는 기능(URL 주소 1)' 이런 식으로 기능별 요청을 받는 각각의 API 주소를 통해 서버로 전달한다. 서버가 요청을 받으면 다시 API를 통해 '비디오 검색어'라는 데이터와 함께 클라이언트에게 응답을 보낸다.

위의 개발자는 API가 아직 미완성이기 때문에 서버로부터 요청 API를 보냈으나 이미지로 응답받지 못했다는 말을 하고 있는 거였다. 그런데 이런 API를 각자 필요한 방식에 맞게 다양하게 설계한다면 어떻게 될까? 많은 개발자들이 각자의 API를 사용해 개발을 한다면 유지 보수하는데 많은 리소스가 들 것이다. 그래서 이러한 문제를 해결하기 위해 일정한 아키텍처의 제약 조건을 준수하는 애플리케이션 프로그래밍 인터페이스를 만들어 사용하기로 했다. 그것이 바로 REST API이다.

REST API & RESTful API

by. 류니

REST API (REpresentational State Transfer) 자원을 이름(자원의 표현)으로 구분해 해당 자원의 상태(정보)를 주고받는 모든 것을 의미한다. 즉, 자원(resource)의 표현(representation)에 의한 상태 전달을 뜻한다. 어떤 자원에 대해 CRUD(Create, Read, Update, Delete) 연산을 수행하기 위해 URI(Resource)로 POST, GET, PUT, PATCH, DELETE의 방식(Method)을 사용하여 요청을 보내며, 요청을 위한 자원은 특정한 형태(Representation of Resource)로 표현된다. REST의 구성요소로는 3가지가 있다. RESTful API는 REST의 설계 규칙을 잘 지켜서 설계된 API를 뜻한다.

by. 류니

1. 자원(Resource) - URI

모든 자원에는 고유한 ID가 존재하고, 이 자원은 Server에 존재

자원을 구별하는 ID는 '/exgroups/:exgroup_id'와 같은 HTTP URI

Client는 URI를 이용해 자원을 지정하고 해당 자원의 상태(정보)에 대한 조작을 Server에 요청

2. 행위(Verb) - Method

HTTP 프로토콜의 Method를 사용

HTTP 프로토콜은 GET, POST, PUT, PATCH, DELETE의 Method를 제공 ( CRUD )

*Method(메소드) = 함수 = 파라미터

3. 표현 ( Representation of Resource )

Client와 Server가 데이터를 주고받는 형태로 JSON, XML, TEXT, RSS 등

JSON, XML을 통해 데이터를 주고받는 것이 일반적

OPEN API

출처 - 도로교통공단

이렇게 잘 설계한 API를 오픈해 제공하는 것을 OPEN API라고 한다. 하나의 웹 사이트에서 자신이 가진 기능을 이용할 수 있도록 공개한 프로그래밍 인터페이스인 것이다. 카카오, 네이버, 구글, 공공데이터 등 이렇게 자사의 서비스 기능을 왜 굳이 모든 사람들에게 공개하는 걸까? 그 이유는 자사의 서비스의 기능을 다양한 서비스에서 활용할 수 있도록 해 서비스의 저변을 넓히는 목적 때문이다. 대기업들은 시장 확대를 목적으로 오픈 API를 운영하기도 하고, 비영리 기관에서는 공공의 목적으로 무료로 API를 제공하는 경우도 있다.

예를 들어 쇼핑몰 앱에서 상담을 목적으로 카카오톡 플러스 친구를 이용하기 위해 카카오톡 플러스 친구 API를 가져와 개발할 수 있다. 미세먼지를 측정하는 앱은 기상청의 공공데이터의 API를 사용해 개발할 수 있다.

OPEN API를 사용하는 앱 중 내가 가장 많이 쓰는 앱은 바로 '카카오 맵'이다. 나는 카카오 맵의 버스 UX/UI 때문에 아주 오래전부터 네이버 지도가 아닌 카카오 맵을 꾸준히 사용하고 있다. 'kakao developers' 페이지에 들어가면 카카오 맵의 iOS OEPN API를 찾아볼 수 있다. 하지만 앱 전용 API는 SDK를 깔아야 해서 내가 확인할 수 없었고 (실제 사용은 가입을 하고 개발자 여부를 승인받은 후 사용이 가능한 것 같다.) '로컬' 카테고리에 들어가면 비슷하게 주소 검색과 같은 기능을 가진 OPEN API를 확인할 수 있다. 카카오 로컬 OPEN API의 기능과 구조를 자세하게 살펴보자.

카카오 로컬 OEPN API

Kakao Developers

카카오 API를 활용하여 다양한 어플리케이션을 개발해보세요. 카카오 로그인, 메시지 보내기, 친구 API, 인공지능 API 등을 제공합니다.

developers.kakao.com

카카오 로컬 API 기능은 주소 검색하기, 좌표로 행정구역 정보 받기, 좌표로 주소 변환하기, 좌표계 변환하기, 키워드로 장소 검색하기, 카테고리로 장소 검색하기가 있다. 카카오 로컬 API는 URL 구조로 REST API이며, GET 메서드(METHOD)를 사용하고 리턴 형식(응답)은 JSON과 XML을 지원하고 있다. 완벽하게 REST 방식을 다 지키는 건 아니라서 RESTful API는 아니다.

카카오 로컬 API 기능과 구조 (출처 - Kakao Developers)

이 기능 중에서 <좌표로 주소 변환하기 기능> 좌표 정보의 지번 주소와 도로명 주소 정보를 반환하는 API를 좀 더 자세하게 알아보자.

카카오 로컬 API 좌표로 주소 변환하기 기능의 <Request> (출처 - Kakao Developers)

카카오 로컬 API 좌표로 주소 변환하기 기능의 <Response> (출처 - Kakao Developers)

Request 값을 이용해 서버에 요청하면 Response 값으로 응답을 받는 구조이다. 좌표로 주소 변환하기 기능은 다음과 같이 해석할 수 있다.

▶︎ Request

URL의 GET 메소드를 사용해 Parameter 함숫값을 적어 서버에 요청하면,

▶︎ Response

meta, documents, Address, RoadAddress 값으로 적어서 응답해 준다.

즉, 실제 들어가는 값으로 설명하자면,

▶︎ Request

주소로 변환하고 싶은 장소의 X좌표 값(경도), Y좌표 값(위도), 좌표 체계 값을 URL 주소로 적어 서버에 요청하면,

▶︎ Response

지번주소와 도로명주소로 전환해 응답해 주는 역할의 API이다.

샘플을 통해 좀 더 자세하게 입출력 구조를 알아보자.

1. Request

(출처 - Kakao Developers)

parameter 함숫값을 보면 x는 경도, y는 위도, input_coord로 입력되는 값에 대한 좌표 체계(기본값: WGS84)로 구성되어 있다.

함숫값으로 위의 URL의 내용을 살펴보면,

x=127.423084873712 경도, y=37.0789561558879 위도 (기본값: WGS84)의 장소의 주소를 변환해달라는 요청이다.

2. Response

위에 첨부한 사진과 함께 봐주세요 (출처 - Kakao Developers)

어떤 응답이 왔는지 차례대로 살펴보자.

1. meta :

total_count - 변환된 지번 주소 및 도로명 주소의 개수가 1개이다.

2. document :

- 지번 주소 상세 정보, 아래 address 항목 구성 요소를 참고해라

- 도로명 주소 상세 정보, 아래 RoadAddress 항목 구성 요소를 참고해라

3. RoadAddress :

4. Address

위의 내용을 정리하면 아래와 같은 내용이다.

경도 127.423084873712 , 위도 37.0789561558879의

도로명 주소는 경기도 안성시 죽산면 죽산초교 길 69-4이고,

지번 주소는 경기 안성시 죽산면 죽산리 343-1이다.

출처 - Kakao Developers

카카오 로컬 OPEN API로 앱과 웹에서 지도를 활용하기 위해서 SDK를 사용해야 한다. 카카오가 제공하는 로컬 OPEN API는 넓은 범위를 한계 없이 사용할 수 있도록 제공하고 있다. 스타트업에서 대부분의 앱을 만들 때 지도가 필요한 경우 직접 만들지 않고 카카오, 네이버, 구글의 지도 API를 사용하기 때문이다.

그렇다면 PM은 왜 API를 알아야 할까?

PM이 직접 API를 만들거나 설계하는 경우는 많지 않다. 하지만 개발자와의 소통을 위해서 우선 먼저 알아야 한다. 그리고 API의 구조가 곧 제품의 정보 교환 구조를 의미하기 때문에, 제품 기능을 이해하고 관리하는 목적에서 자사 제품의 API를 파악하고 분석할 수준의 능력은 갖는 것이 중요하다.

그럼 오늘 알아본 카카오 로컬 OPEN API를 실제 제품 개발에 사용한다고 가정해 보자. 만약 우리 서비스가 네이티브 앱이나 하이브리드 앱처럼 모바일 기기의 API를 사용할 수 있는 경우 GPS 기능을 사용할 수 있을 것이다. 그렇다면 이 GPS에서 사용자의 위도와 경도 정보를 파악해 도로명이나 지번 주소로 나타낼 수 있을 것이다. 내 위치를 기준으로 내가 속해있는 구, 동의 위치 정보가 필요한 배달 앱에서 활용할 수 있을 것이다. 또한 다양한 카테고리로 지도 내에서 검색이 가능하기 때문에, 주변 가게와 식당 정보를 알려주는 맛집 검색, 핫 플 검색과 같은 서비스를 제공하는 앱에서도 활용할 수 있을 것이다.

출처 - 카카오맵 블로그

하지만 이런 OPEN API를 사용할 경우 문제가 발생하는 경우는 위와 같은 상황이다. 카카오가 다음을 인수하고 나서 다음에서 제공하던 API가 모두 카카오의 API로 바꾸게 된 것이다. 이때 카카오 측에서 바로 API에 종료 문구가 보이도록 표기해버리는 바람에, 다음 지도 API를 사용하고 있던 많은 서비스들이 난감한 상황에 처했다고 한다. 다음 지도 종료 안내 문구를 앱 서비스 종료로 착각해서 문의하는 고객들이 많아져 불편을 겪었다고 한다. 이처럼 OPEN API를 배포하는 측에서 내리는 결정에 따라 이를 사용하고 있던 다른 서비스들이 피해를 보거나 불편한 상황이 생길 수가 있다.

추가로 위의 OPEN API를 사용하는 방식처럼 카카오 맵 iOS OPEN API를 URL을 이용해 아이폰의 단축어 기능에서 사용할 수 있다.

https://apis.map.kakao.com/ios/guide/#urlscheme_move_to_coord

내가 설정해둔 단축어는 내 집 주소를 위도와 경도 값을 각각 lat, long 함수에 입력하면 주소로 변환해서 나온다. 여기에 추가적으로 걸어서, 대중교통, 차 수단을 선택하는 함수를 추가하고 카카오 맵 url 열기까지 추가해 주면, 카카오 맵에서 길 찾기 하는 화면으로 바로 검색되어서 나온다.

(집 주소 때문에 (위도)(경도)라고 표시되어 있습니다. 그 부분에 실제 위도, 경도를 작성하면 됩니다! 그리고 구동되는 모습도 올리고 싶었는데, 집 주소가 너무 적나라하게 나와서...! 방구석 리뷰룸님의 유튜브를 대신 첨부합니다!)