클라이언트와 서버의 대화 방법, API
[코드스테이츠 PMB 11] Ep26. API, Open API
개발자와 기획자는 어떻게 다를까?
개발자와 기획자의 뇌 구조 / 출처: Slowalk기획자 : "지난주에 요청드린 작업 언제까지 될까요?"
개발자 : "아 그게 서버에서 이미지 URL을 보내줘야 하는데, API가 미완성인 것 같아요. JSON에 아이콘 URL만 빠져있네요... 클라는 URL이 안 오면 기본값이 뜨게 해 놨어요. 근데 제가 임의로 만들어서 좀 이상하게 보일 겁니다."
- 「비전공자를 위한 이해할 수 있는 IT 지식」中
이 상황에서 기획자는 이런 생각이 든다.
'그래서 끝났다는 건가? 언제까지 되느냐고 물어봤는데 뭐라는 거야?'
기획자는 개발자와 소통하다 이런 상황이 종종 발생하기도 한다. 서버? URL? JSON? 이게 다 무슨 말일까.
개발자와의 원활한 커뮤니케이션을 위해 개발자의 용어를 이해할 필요가 있다. 오늘은 API와 RESTful API, Open API에 대해 알아보고 인터넷에 Open API로 공개되어 있는 서비스를 살펴볼 것이다.
1. API란 무엇일까?
API(Application Programming Interface)는 애플리케이션 소프트웨어를 빌드하고 통합하기 위한 인터페이스이다. API는 프로그램들이 서로 상호작용하는 것을 도와주는 매개체이자 규칙으로 볼 수 있다.
인터페이스? 매개체?(...) API의 정의는 이러하지만 개념이 잘 와닿지 않는다. 좀 더 이해를 쉽게 하기 위해 비유를 들어 보겠다.
어느 날 맛있는 식사를 하기 위해 멋진 레스토랑을 방문했다고 가정해보자. 점원이 가져다준 메뉴판을 보면서 먹음직스러운 스테이크를 고르면 점원이 주문을 받아 요리사에 요청을 할 것이다. 그러면 요리사는 정성껏 스테이크를 만들어 점원에게 주고, 우리는 점원이 가져다준 맛있는 음식을 먹을 수 있게 된다.
여기서 점원의 역할을 한 번 살펴보겠다. 점원은 손님에게 메뉴를 알려주고, 주방에 주문받은 요리를 요청한다. 그다음 주방에서 완성된 요리를 손님께 다시 전달한다. 바로 API는 점원과 같은 역할을 한다.
API는 손님(프로그램)이 주문할 수 있게 메뉴(명령 목록)를 정리하고, 주문(명령)을 받으면 요리사(응용프로그램)와 상호작용하여 요청된 메뉴(명령에 대한 값)를 전달한다.
쉽게 말해, API는 프로그램들이 서로 상호작용하는 것을 도와주는 매개체로 볼 수 있다.
API의 역할
1. 서버와 데이터베이스에 대한 출입구 역할을 한다.
데이터베이스에는 정보들이 저장되는데 모든 사람들이 이 데이터베이스에 접근할 수 있으면 안 될 것이다. API는 이를 방지하기 위해 여러분이 가진 서버와 데이터베이스에 대한 출입구 역할을 하며, 허용된 사람들에게만 접근성을 부여해준다.
2. 애플리케이션과 기기가 원활하게 통신할 수 있도록 한다.
API는 애플리케이션과 기기가 데이터를 원활히 주고받을 수 있도록 돕는 역할을 한다.
3. 모든 접속을 표준화한다.
API는 모든 접속을 표준화하기 때문에 기계/운영체제 등과 상관없이 누구나 동일한 액세스를 얻을 수 있다. 그래서 API는 범용 플러그처럼 작동한다고 볼 수 있다.
2. REST API와 RESTful API
REST
REST(Representational State Transfer)는 자원을 이름(자원의 표현)으로 구분해 해당 자원의 상태(정보)를 주고받는 모든 것을 의미한다. 즉, 자원(resource)의 표현(representation)에 의한 상태 전달을 뜻한다.
자원은 해당 소프트웨어가 관리하는 모든 것으로 문서, 그림, 데이터, 해당 소프트웨어 자체 등이다. 자원의 표현은 그 자원을 표현하기 위한 이름이다. 예를 들어, DB의 학생 정보가 자원일 때, 'students'를 자원의 표현으로 정한다. 상태(정보) 전달은 데이터가 요청되는 시점에서 자원의 상태(정보)를 전달한다. JSON 혹은 XML을 통해 데이터를 주고받는 것이 일반적이다.
REST는 기본적으로 웹의 기존 기술과 HTTP 프로토콜을 그대로 활용하기 때문에 웹의 장점을 최대한 활용할 수 있는 아키텍처 스타일이며, 네트워크 상에서 Client와 Server 사이의 통신 방식 중 하나이다.
REST의 구성 요소
1. 자원(Resource) : URI
모든 자원에 고유한 ID가 존재하고, 이 자원은 Server에 존재한다.
자원을 구별하는 ID는 ‘/groups/:group_id’와 같은 HTTP URI 다.
Client는 URI를 이용해서 자원을 지정하고 해당 자원의 상태(정보)에 대한 조작을 Server에 요청한다.
2. 행위(Verb) : HTTP Method
HTTP 프로토콜의 Method를 사용한다.
HTTP 프로토콜은 GET, POST, PUT, DELETE와 같은 메서드를 제공한다.
3. 표현(Representation of Resource)
Client가 자원의 상태(정보)에 대한 조작을 요청하면 Server는 이에 적절한 응답(Representation)을 보낸다.
REST에서 하나의 자원은 JSON, XML, TEXT, RSS 등 여러 형태의 Representation으로 나타내어질 수 있다.
JSON 혹은 XML를 통해 데이터를 주고받는 것이 일반적이다.
REST API
REST API / 출처: AppMaster REST API란 REST 아키텍처의 제약 조건을 준수하는 애플리케이션 프로그래밍 인터페이스를 뜻한다. API는 정의된 규칙이기 때문에 개발자가 직접 정의할 수도 있지만, 수많은 규칙들이 존재하고 서로 상이하다면 정보 교환이 어려워진다. 그래서 규칙을 통일하게 되었고 이때 만든 통일된 규칙이 Rest API이다. 최근 OpenAPI, 마이크로 서비스 등을 제공하는 업체 대부분은 REST API를 제공한다.
REST API의 가장 큰 특징은 각 요청이 어떤 동작이나 정보를 위한 것인지를 그 요청의 모습 자체로 추론이 가능하다는 것이다. HTTP 표준을 기반으로 구현하므로, HTTP를 지원하는 프로그램 언어로 클라이언트, 서버를 구현할 수 있다.
REST API의 구성 요소
1. 클라이언트 : 통신을 시작하는 사용자 측(자신의 장치에서)에서 시작된 클라이언트 또는 프로그램
2. 서버 : API를 기능 및 데이터에 대한 액세스로 사용하는 서버
3. 자원 : 서버가 클라이언트에 전송하는 모든 콘텐츠(비디오, 텍스트, 사진).
REST API의 작동 방식
REST API는 HTTP 요청을 통해 통신하여 데이터 생성, 읽기, 업데이트 및 삭제 기능을 완료한다. CRUD(Create, Read, Update, Delete) 연산이라고도 하며, REST는 요청된 리소스에 대한 정보를 제공하고 리소스로 수행할 작업을 설명하는 네 가지 방법을 사용한다.
HTTP Methods
HTTP 프로토콜은 GET, POST, PUT, DELETE의 Method를 제공한다.
· GET — Read : 리소스 요청 (불러와줘)
· POST — Create : 리소스 생성 (생성해줘)
· PUT — Update : 리소스 업데이트 (바꿔줘)
· DELETE — Delete : 리소스 삭제 (지워줘)
RESTful API
RESTful은 REST의 설계 규칙을 잘 지켜서 설계된 API를 뜻한다. 일반적으로 REST라는 아키텍처를 구현하는 웹 서비스를 나타내기 위해 사용되는 용어이다. RESTful하게 만든 API는 요청을 보내는 주소만으로도 어떤 것을 요청하는지 파악이 가능하다고 한다.
3. Open API
Open API는 누구나 사용할 수 있도록 공개된 API이다. 즉, API 중 플랫폼 기능, 콘텐츠를 외부에서 웹 프로토콜(HTTP)로 호출하여 사용할 수 있게 개방한 API를 의미한다.
처음부터 모든 것을 개발하려면 시간과 비용이 많이 들겠지만 Open API를 사용하면 유용한 기능들을 빠르게 구현할 수 있는 장점이 있다. Open API를 사용하면 서비스 사용자는 키를 발급받을 수 있는데 해당 키에 따라 할당량을 부여받고, 할당량을 초과할 경우 과금되기도 한다.
그렇다면 기업에서 API를 제공하는 이유는 무엇일까?
API를 통해 정보 및 기능을 제공함으로써 더 많은 이익을 얻을 수 있기 때문이다. 정부와 공공기관은 공적인 목적으로 활용할 수 있는 Open API를 제공한다. 공적인 목적의 활용은 사회 전체에 긍정적인 영향을 줄 수 있다.
기업은 Open API를 제공하면 해당 서비스의 영향력을 확대시킬 수 있는 밑거름이 된다. 간편 소셜 로그인으로 많이 활용하는 카카오, 네이버, 페이스북, 구글 API는 쉽고, 빠르게 개발할 수 있도록 도와주지만 그만큼 이러한 기업들의 영향력이 커진다고 볼 수 있다.
Open API 제공
4. 카카오톡 소셜 Open API
Open API를 사용하는 앱 중 내가 가장 많이 쓰는 앱은 '카카오톡'이다. 전 국민이 가장 많이 사용하는 앱이기도 한 '카카오톡 소셜' Open API에 대해 한번 살펴볼 것이다. 'kakao developers' 페이지에서 '카카오톡 소셜'의 API(참고)를 확인할 수 있다.
카카오톡 프로필 및 친구 정보를 활용한 서비스 UI 예시 / 출처: kakao developers카카오톡 소셜 API는 서비스에 가입한 사용자의 카카오톡 프로필과 친구 정보를 제공하는 API이다. 카카오 로그인을 도입한 앱에서 사용할 수 있으며, 서비스 UI를 통해 사용자 카카오톡 프로필 이미지와 닉네임을 보여줄 수 있도록 한다. '서비스 내 친구 목록' 개인 정보 제공에 동의한 친구들의 프로필도 조회할 수 있다.
제공 기능
카카오톡 소셜 API는 서비스에서 카카오톡 소셜 기능을 구현할 수 있도록 카카오톡 친구 데이터를 제공한다. 카카오톡 친구의 기본 정보와 프로필 데이터를 목록 형태로 제공한다.
이 API는 서비스의 소셜 기능 강화를 위해 활용할 수 있다. 사용자 프로필과 친구 데이터를 서비스 UI에 맞게 출력하여 카카오톡 친구 목록을 보여줄 수 있고, 서비스 회원 정보와 결합하여 사용자 활동을 친구끼리 공유하는 등 더욱 강력한 소셜 기능을 구현할 수도 있다.
예를 들어, 관심사 기반 커뮤니티 앱에서 소셜 활동을 목적으로 온라인 모임을 개설하기 위해 카카오톡 친구 목록 API를 가져와 개발할 수 있을 것이다.
지원 범위
카카오톡 소셜 API의 Kakao SDK 지원 여부 및 사용자 연결 상태에 따른 호출 제한에 관한 내용으로, 어떤 소프트웨어 개발 도구를 지원하는지를 알려준다. 개발자들은 이를 보고 카카오 API를 사용한 서비스 설계 시 참고하게 되며, 카카오톡 소셜의 경우 모든 SDK를 지원하고 있다.
카카오톡 소셜 SDK 지원범위API 구현 방법
카카오톡 소셜의 기능 중 '친구 목록 가져오기' 기능의 API 구현 방법을 좀 더 자세히 알아보겠다.
'친구 목록 가져오기' 기능의 RepuestRequest 값을 서버에 요청하면 Response 값으로 응답을 받는 구조이다. 액세스 토큰을 헤더에 담아 GET으로 요청한다. 정렬 순서, 한 페이지에 가져올 친구 수 등 파라미터를 선택적으로 사용할 수 있다.
'친구 목록 가져오기' 기능의 Response응답은 JSON 객체로 받게 되는데, 카카오톡 친구 수가 요청 시 Parameter에 나와있는 limit보다 많다면 결과가 여러 페이지로 나뉜다. 이 경우, 직접 개별 Parameter를 지정하지 않고도 액세스 토큰과 응답에 포함된 after_url로 GET 요청을 해 다음 페이지의 친구 목록을 받아올 수 있다. 사용자 카카오 계정에 연결된 카카오톡이 없다면 에러 응답을 받는다.
'친구 목록 가져오기' 기능의 FriendParameter 중 친구 정보를 정렬하는 기준은 order와 friend_order으로 설정한다. 만약 친구 목록 응답에 즐겨찾기 친구들을 먼저 나오게 하고 싶다면 order는 'asc', friend_order은 'favorite'으로 지정한다. 즐겨찾기 여부와 관계없이 닉네임 오름차순으로 친구 목록을 받아보려면 order는 'asc', friend_order은 'nickname'으로 지정한다.
API의 입출력 구조
카카오톡 소셜 Open APO 페이지의 샘플을 통해 입출력 구조를 간단하게 살펴보면 아래와 같다.
Parameter에서 설명하고 있는 limit값은 한 페이지에 가져올 친구 최대 수(기본값: 10, 최대: 100)이다. 따라서 첫 번째 URL을 보면, 카카오톡 친구 3명의 정보를 요청하고 있다.
offset값은 친구 목록 시작 지점(기본값: 0), order값은 친구 목록 정렬 순서이며 오름차순(asc) 또는 내림차순(desc)(기본값 asc) 임을 확인하였다.
두 번째 URL의 경우, 한 페이지에 가져올 친구 수는 3명이고 친구 목록 시작 지점 또한 3명이므로 친구 목록 다음 페이지에 대한 요청이다. 친구 목록 정렬은 오름차순이다.
Reponse를 보면 3가지 응답 형태가 동일해 대표적으로 첫 번째 응답만 살펴보았다.
after_url : 친구 목록 다음 페이지 URL ("URL")
elements : 각 친구 정보를 담은 JSON배열
* JSON: Javascript 객체 문법으로 구조화된 데이터를 표현하기 위한 문자 기반의 표준 포맷
id : 회원번호 (00000000001)
uuid : 친구마다 고유한 값을 가지는 참고용 코드(Code) ("abcdefg0001")
favorite : 해당 친구 즐겨찾기 여부 (true)
profile_nickname : 프로필 닉네임 ("이수민")
profile_thumbnail_image : 프로필 썸네일 이미지 (이미지 URL)
allowed_msg : 메시지 차단 여부(true: 수신 허용, false: 수신 거부) (True)
total_count : 전체 친구 수 (11)
favorite_count : 즐겨찾기(favorite) 친구 수 (1)
오늘은 API와 REST API, 그리고 카카오톡 Open API의 기능과 구현 방법, 입출력 구조에 대해 알아보았다. 카카오톡 Open API를 통해 '카카오톡 친구 목록 불러오기 기능'이 어떤 코드로 구성되어 있는지 간단하게나마 살펴보았고 URL, 함숫값, 각 기능 정의 등 데이터의 상호작용을 위한 규칙에 따라 API가 구현된다는 것도 새롭게 알게 되었다. 분석하는 게 역시나 쉽지는 않았다..ㅎㅎ
공공데이터의 OPEN API를 활용한 흥미로운 사례(참고)들도 많았는데, 여기에서 수많은 비즈니스가 만들어지고 있었다. 식품의약품안전처에서 제공해주는 화장품 성분 정보를 사용하여 화장품 유해성 물질을 알려주는 앱이나, 지자체의 정보를 사용하여 관광정보를 보여주는 앱 등 실생활에 많이 사용되고 있었다.
다음엔 이처럼 공공데이터를 활용한 서비스들을 찾아보고 싶다. 혹시나 새로운 비즈니스 아이디어가 떠오를 수도..! 아이디어와 실행의 영역은 다르긴 하지만 말이다.
참고자료
「비전공자를 위한 이해할 수 있는 IT 지식」 (최원영)
https://brunch.co.kr/@businessinsight/65#comment
https://brunch.co.kr/@operator/65
https://gmlwjd9405.github.io/2018/09/21/rest-and-restful.html
https://appmaster.io/ko/blog/rest-apiran-mueosimyeo-dareun-yuhyeonggwa-eoddeohge-dareungayo
https://dev-coco.tistory.com/97
