순도 100% 문과생과 함께 API 개념 이해해보기
API, REST API, 오픈 API 개념 #코드스테이츠 PMB 8기
드라마 스타트업 (합성이 즐거웠다)당신은 지금 A 스타트업의 인턴 기획자다. 그리고 뭔가 프로덕트에 문제가 생겼다. 팀장님이 이거 왜 이러는지 알아오라셔서 간 개발팀, 남주혁이 대답했다.
"아 그게 서버에서 이미지 URL을 보내줘야 하는데 API가 미완성인 거 같아요 JSON에 URL만 빠져있네요 클라는 URL이 안 오면 기본값이 뜨게 해놨어요 근데 제가 임의로 만들어서 좀 이상하게 보일 겁니다"
이해할 수도, 외울 수도 없는 이 말, 어떻게 하면 좋을까..? (왠지 수지님이 눈으로 욕하는 거 같아 보인다) 스타트업의 수지님을 이미지로 쓰긴 했지만 서비스 기획 인턴으로 일했던 당시 내가 종종 겪었던 일이다.. 기획/마케팅 베이스 덕분에 인턴 기회를 잡을 수 있었지만, 개발 지식이라곤 하나도 없던 나. "토큰이 만료되어서..", "서버가... 블라블라... 핫픽스 바로 진행해야 할 거 같은데" 한마디 한마디가 리스닝 시험 같았다. 그 과정에서 내가 정말 귀가 닳도록 들었던 단어, 바로 API다.
오늘 글에서 다뤄볼 API에 대한 개념은 위 글에서 정말 정말 잘 설명하고 있어 링크를 먼저 공유한다. 설명 방식을 차용하기도 했고, 정말 이해가 쏙쏙 감탄하면서 읽은 글이라 꼭 꼭 추천합니당
API는 약속이다!
Application Programming Interface 뜻 그대로 풀어보면 "어플리케이션을 + 프로그래밍하는데 필요한 + 인터페이스"다. IT 서비스 내에서 정보의 소통이 일어나는 서버와 클라이언트에서, 서로 정보를 어떻게 주고받을지 미리 형태를 정한 것이 바로 API라고 한다. 이렇게 들으니 영 감이 안 온다... API의 목적에 대해 간단히 이해할 수 있었던 영상을 소개한다.
"엄마가 출금을 해야 하는데 대출 창구로 갔어, 그러면 출금을 할 수 없어. 이번엔 출금 창구로 잘 갔어, 그런데 대출 서류로 잘못 들고 갔어." 은행의 규칙을 지키지 않아서 출금을 할 수 없는 어머니 8ㅅ8 여기서 어머니 = 클라이언트, 은행 = 서버, 돈 = 요청 정보라고 대입해보면 이해가 조금 쉬워진다. API는 "약속", 어기면 요청한 정보를 줄 수 없다. 요구하는 조건을 충족해야 답을 얻을 수 있게 만든 '서버와 클라이언트의 약속'이 API인 것이다.
예시를 하나 더 들어보자, 미세미세, 네이버 날씨 정보, 기본 날씨 앱 등등 우리는 저엉말 많은 곳에서 기상청 데이터를 받아 쓰는 것을 볼 수 있다. 그런데, 이 앱들이 매 시간, 매 분마다 기상청에게 정보를 요청할 때 기상청에서 일일이 요청정보를 확인하고 담당자가 일일이 서버에서 정보를 보내주는 것은 불가능한 일이다. (과로사..) 이런 문제를 해결하기 위해 API가 있는 것이다.
이전에는 "서버야 미세먼지 데이터 좀 줘"라고 말했던 것을 -> [서버야 / 줘 / 미세먼지 정보]처럼 하자는 약속을 맺은 거다. 이렇게 정리된 약속 덕분에 서버가 알아서 [미세먼지][강우량]처럼 해당하는 위치에 오는 애들을 딱딱 분업해서 처리할 수 있게 된다. 데이터를 주고받기 위해 정리된 약속, 대화의 규칙을 바로 API라고 부르는 것이다. 이미지출처
REST API
이번엔 이상한 상상을 하나 해보자. 앞으로 남동생이 나에게 시간을 물을 때는 "지금 몇 시야?" 대신 "시계 얼굴 보았니?"라 하기로 정했다. 그래서 택배 아저씨가 방문했을 때 "지금 몇 시인가요?"라고 물으면 나는 대답을 안 해줄 것이다. 우리 집의 약속에 따르면 "시계 얼굴 보았니?"로 물어야 하기 때문이다.
ㅋㅋㅋ이상해도 약속은 약속이다. API도 서비스마다 원하는 방식으로 규칙을 정할 수 있다. 하지만 멋대로 정한 약속 아래에서는 문제가 발생하기 마련이다. 서버(나)와 클라이언트(남동생)는 약속을 알고 있고, 서로 대화할 수 있지만, 다른 서비스(택배 아저씨)가 정보를 요청할 때 불편함이 생겼다.
이 이상한 상상처럼, 서비스마다 각기 다른 API를 사용하는 과정에서 전 세계 개발자들이 "안 되겠다! 통일하자!" 해서 태어난 것이 바로 REST API다. REST API(Representational State Transfer)는 자원을 '자원의 이름'으로 구분해 정보를 주고받는 API를 의미한다. 즉, 자원(Resouce)의 표현(Representation)에 의해 상태를 전달하는 API이다.
REST의 구성요소
REST API에 대해 알아보기 전, REST 부터 알아보자. REST(Representational State Transfer)는 월드 와이드 웹과 같은 분산 하이퍼미디어 시스템을 위한 소프트웨어 개발 아키텍처의 한 형식이다(...) 구체적으로는 웹상에서 사용되는 여러 리소스를 HTTP URI로 표현하고, 그 리소스에 대한 행위를 HTTP 메소드로 정의하는 방식을 의미한다. 이해가 안 되는 개념이 많지만, REST API를 이해하기 위해 지금은 '구조'에 먼저 집중해보자. (이해/작성에 참고한 감사한 글<<<)
(1) Resource(자원) = URI(Uniform Resource Identifier)
URI는 해당 사이트의 특정 리소스 위치를 나타내는 유일한 주소를 의미하며, https://localhost:5000/news/10 와 같이 모든 것을 Resource(명사)로 표현하고, 세부 리소스에는 id를 붙인다. 클라이언트는 URI를 이용해서 자원을 지정하고, 해당 자원의 상태(정보)에 대한 조작을 서버에 요청한다.
(2) Method(행위)
자원에 대한 행위를 나타내며, HTTP 프로토콜의 Method를 사용한다. REST API는 HTTP라는 규약에 따라 신호를 전송한다. 그리고 이 HTTP의 다양한 메소드(함수) 중 REST API에서는 표에 있는 것처럼 4-5가지를 사용한다. 표를 보면, 데이터를 다룰 때 기준이 되는 기본적인 요청인 C.R.U.D에 맞춰 명령어가 구성되어 있다. (*기획자는 데이터 흐름을 항상 CRUD 관점에서 볼 수 있어야 한다! 수정은 있는데 업로드가 없다던가 하면 안 되니까) 그리고 요청(Request)에 약속이 있듯, 응답(Response)에도 약속이 있다. 200, 400, 500 이런 식으로 문제 여부, 원인까지 확인할 수 있다.
(3) Representation(표현)
JSON 등을 통해 서버와 클라이언트가 주고받는 표현(응답)을 의미한다.
그리고 RESTful API는 위의 REST 원리를 잘 따르는 API를 의미한다. REST를 따르면 여러 장점들이 있는데 그중 가장 명확한 점은 self-descriptiveness 인데, 이 자체만으로도 API 목적이 쉽게 이해가 되기 때문이다. 즉, 구조를 이루는 리소스와 메소드만 봐도 이 요청이 어떤 행위를 하는지 직관적으로 이해가 가능하다는 것이다! 예시로 직접 보자.
OPEN API
너무 원론적인 이야기만 했지만, 다시 API가 뭐냐 간단히 정리해보면 어떤 기능을 누구나 쉽게 사용할 수 있도록 모듈화한 인터페이스 정도로 볼 수 있을 것 같다. 프렌즈팝을 카카오톡 로그인할 수 있는 것도, 음식점 추천 앱에서 구글 맵을 볼 수 있는 것도 다 API 문서 덕이다. 그리고 이렇게 외부에 공개되어 있는 API를 OPEN API라고 하고, 이 OPEN API를 사용해 개발하면 시간, 공수를 줄일 수 있다.
모든 API가 OPEN API는 아니다. 회사 개발자가 자체 제품/서비스 개선을 위해 내부적으로 사용하는 Private API, 데이터 공유에 동의하는 특정인들에게만 회사가 사용 권한을 오픈하는 Partner API도 있다. 그렇다면 API를 오픈하는 장점은 뭘까? 플랫폼 서비스의 경우, 자사 서비스의 생태계를 확고히 해 시장을 확대하기 위한 것이 주목적이다. 그리고 공공기관 API는 공익적 목적으로 API를 공개하고 있다. e.g. 기상청 데이터 API
카카오 로컬 OPEN API 살펴보기
여기까지 오는데 정말 길었다.. 이제 실제 OPEN API를 뜯어보면서 배운 것들을 확인해보자! Kakao Developers 사이트에 가면 로컬 외에도 우리에게 친숙한 카카오 로그인, 네비, Pay 등 다양한 오픈 API를 확인하고 사용할 수 있다 : >
카카오 로컬 API
카카오 로컬 API는 키워드로 특정 장소 정보를 조회하거나, 좌표를 주소/행정구역을 변환하는 등 장소에 대한 정보를 제공하는 API다. (앱/웹에서 카카오맵을 사용하고 싶으면 카카오 지도 SDK를 사용해야 한다!) 주소 검색, 좌표를 통한 다양한 정보, 키워드로 장소 검색 등의 API를 이용할 수 있고, 이 API들을 카테고리화해 로컬 API라고 부르고 있는 것 같다.
카카오 로컬 API의 개발 가이드로 들어가면 테스트 도구, 각 API 기능에 대한 코드 예제와 설명을 볼 수 있다. 카카오 로컬 API는 REST API로 JSON/XML 형식을 따르고 있다는 점을 확인할 수 있었다 : > 나는 그중 가장 기본기능인 주소 검색하기 기능을 좀 더 파헤쳐보기로 결정!
주소 검색하기 기능
주소를 지도 위에 정확하게 표시하기 위해 해당 주소의 좌표 정보를 제공하는 API로 주소에 해당하는 지번 주소, 도로명 주소, 좌표, 우편번호, 빌딩명 등의 다양한 정보를 함께 제공합니다. 애플리케이션 REST API 키를 헤더에 담아 GET으로 요청합니다. 원하는 검색어와 함께 결과 형식 파라미터의 값을 선택적으로 추가할 수 있습니다. 이 API는 지번 주소, 도로명 주소 모두 지원합니다.
여기서 Parameter는 함수의 변숫값이라 할 수 있다. 내가 읽어 들이고(Read)싶은 내용이 있다면, GET 명령어로 궁금한 Parameter 값을 넣어 요청(Request)하면 된다. 이후 카카오 서버에서 요청한 데이터를 응답(Response)한다. 여기서 Type, Required의 의미를 잘 모르겠지만... 일단 넘어가자 ㅎㅎ
응답에는 다양한 데이터가 포함되는 것 같다. 아직 JSON에 대해서 배우지 못해 코드를 제대로 읽진 못하는 상태지만, GET 명령어 요청에 대해 meta/documents/adress/RoadAdress 등의 정보가 응답에 포함되어 오는 것 같다. 샘플을 한 번 살펴보자.
Request
표에서 보면 query = 검색을 원하는 질의어라고 디스크립션이 정의되어있다. 즉, 지금 GET 명령어로, "전북 삼성동 100"이라는 파라미터를 입력해 정보를 읽어 들이길 원하고 있는 것으로 보인다.
Response
meta 데이터부터 보면, tatal_count(검색어에 검색된 문서 수) = 4개, pageable_count(total_count 중 노출 가능 문서 수) = 4, is_end(현재 페이지가 마지막 페이지인지 여부) = true 라고 응답값이 왔다. 한 페이지 안에 4개의 검색 결과가 노출되었다는 것을 알 수 있다! 그 아래에, document / Adress/ road_adress에 대한 정보가 순차적으로 나와있는 것도 볼 수 있다. 카카오 로컬 개발 가이드에 각 Parameter의 정의와 대조해보며 코드를 보면, "전북 삼성동 100"에 대한 정보를 코드로 쭉 알아볼 수 있다. (왜 뿌듯하지 ㅎㅎㅎㅎㅎ)
도대체 뭐라는 거야?
지금 내 표정인데?도대체 뭐라는 거야~~~~!!! 지금까지의 모든 글 중 가장 무지에 고통받으며 쓴 글이다. 장장 8시간 정도 글을 쓰면서 3시간 정도는 머리를 부여잡고 머릿속에 빠져있는 부분들을 구글링으로 채워가느라 너무 고생했다 하하.
그래도 그 시간 동안 API, URI, URL 개념들이 머릿속에 어느 정도 자리 잡을 수 있었다. REST API 예시를 조금이나마 읽게 되었으니 꽤나 큰 수확이다!
다 써놓고 봐도, 내가 100% 이해하지 못한 부분은 툭 치고 넘어간 티가 많이 나서 부끄럽습니다.. 이해가 어려웠던 이유를 생각해보니, PM을 하겠다면서 인터넷 환경에 대해 기초적인 지식이 너무 부족한 게 문제였다. HTTP라던가 프로토콜이라던가... API에 대해 설명하는 글을 읽어도 '기초적인 부분'은 알고 있을 거라 생각하고 적힌 글이 많아 평소보다 읽는데 2배 3배 노력해야 했다 : > 하하 내일 당장 비전공자도 이해할 수 있는 IT 지식 책 사러 가야겠다 하하
이번 블로깅에도 개발자 친구의 도움을 많이 받았다. 매번 댓글 달아주는 덕분에 API에 대해 더 잘 이해할 수 있었다! 고마워 친구!
