읽고싶은 책, 읽은 책을 검색해서 독서 기록을 추가하는 서비스를 만들고 싶다고 생각해 봅시다. 가장 중요한 기능은 1. 책을 검색하고, 2. 검색된 결과값(책 제목, 표지, 지은이, ISBN, 요약글 등)을 추가하는 것이겠죠. 자, 그렇다면 세상에 있는 모든 책들을 다 찾아서, 이미지를 촬영하고, 제목을 넣고, 요약글을 쓰고, 저자를 기입해서, DB를 구축하고, 검색 기능을 구현해야 할까요? 외서는요? 신간이 추가되면요? 책 상세정보가 업데이트되면요? 만약 그런 방식으로 서비스를 만들면 5년이 훌쩍 지날 것 같습니다. 책 검색 기능을 제공하는 도서 관련 프로덕트는 많습니다. 그렇다면 그런 프로덕트는 어떻게 개발 기간을 단축했을까요? 바로 API를 이용했기 때문입니다.
API를 간략하게 설명하자면, '이미 구현된 프로세스를 가져와 사용하는 것'입니다. 위의 예시에서는 책 검색에 해당하는 프로세스를 API로 개발할 수 있을 것 같습니다. 직접 위의 과정을 모두 구현하지 않아도 네이버, 카카오, 알라딘 등에서 제공하는 책 검색 API, 즉 이미 구현된 책 검색 프로세스를 가져와 내 서비스에 붙일 수 있는 것이죠. 오늘은 9월 28일자에서 다뤄보았던 북적북적과 알라딘 책 검색 API를 조금 더 디벨롭시켜 API를 통해 무엇을 주고받는지 알아보고자 합니다.
1. HTTP란?
API에 대해 알아보기 전, 먼저 '통신'에 대해 먼저 알아보고자 합니다. HTTP는 HyperText Transfer Protocol의 약자로, 컴퓨터들끼리 HTML파일을 주고받을 수 있도록 하는 소통 방식입니다. HTTP는 클라이언트 측에서 요청(Request)를 보내고, 서버로부터 응답(Response)를 받는다는 특징을 가지고 있습니다. 또한 각 통신이 독립적이기 때문에, 과거의 요청-응답 내역을 알지 못합니다. 따라서 각 통신마다 필요한 모든 정보를 담아 요청을 보내야 한다는 특성(Stateless)을 가지고 있습니다.
Request는 말 그대로 클라이언트가 서버에게 요청하기 위한 메세지입니다. 보통 Request 메세지는 아래와 같이 구성됩니다.
| Start Line | 요청의 첫번째 줄 | HTTP Method | 어떤 요청인지 정의(GET, POST, DELETE) |
| Request target | 해당 request가 전송되는 목표 URL | ||
| HTTP Version | 사용되는 http 버전 | ||
| Header | 요청에 대한 메타데이터(추가 정보) | key : value | 요청을 보내는 타깃의 주소, 요청을 보내는 클라이언트에 대한 정보, 해당 요청이 보내는 메세지 body 타입, body 길이, 로그인 토큰 등 |
| Body | 요청의 실제 내용 | body | 요청의 실제 내용. 보통 POST일 때 body의 내용이 있다. |
Response 역시 세 부분으로 구성됩니다.
| Start Line | 응답 처리 상태 표시 | HTTP Version | 요청의 HTTP 버전과 동일 |
| Status Code | 응답 메세지의 상태 코드 | ||
| Status Text | 상태를 간략하게 설명해주는 텍스트 | ||
| Headers | 응답의 메타데이터(추가 정보) | 응답에 대한 메타데이터 | |
| Body | 요청의 Body와 일반적으로 동일 | 응답의 형태에 따라 body가 없을 수 있음 | |
정리하자면, HTTP는 "우리 무엇을 요청하고 돌려줄 때 이런 형태로 하기로 하자"라고 정해둔 소통 규약이라 볼 수 있으며, API를 사용하기 위해서도 당연히 이 소통 규약을 지켜야 합니다. 일반적으로 HTTP를 통해 요청과 응답을 주고받는 API를 HTTP API라고 합니다.
2. REST API
API란, 이미 구현된 프로세스를 가져와 사용하는 것이며 이를 사용하기 위해 HTTP라는 통신 규약이 필요함을 살펴보았습니다. 그렇다면 REST API란 무엇일까요? REST API란, 규약이나 프로토콜보다는 디자인 가이드와 비슷하다고 이해하면 될 것 같습니다. HTTP API가 HTTP라는 통신 규약을 사용해 소통하는 넓은 의미의 API라고 본다면, REST API는 아래와 같은 제약 조건이 추가된 것이죠. REST API가 되기 위한 조건은 아래와 같습니다.
- 자원의 식별
- 메시지를 통한 리소스 조작
- 자기서술적 메시지
- 애플리케이션의 상태에 대한 엔진으로서의 하이퍼미디어
각각의 조건을 자세히 살펴보기에는 무리가 있을 듯해 REST API라는 디자인 가이드를 지키고자 하는 이유에 대해 정리해보자면 아래와 같습니다.
- 주소와 메소드만으로도 요청의 내용을 알아볼 수 있도록 하기 위함
- 주소가 곧 서버의 자원을 정의하기 때문에 클라이언트 측에서 요청의 내용을 표시할 수 있도록 하기 위함
- iOS, 안드로이드, 웹, 다른 서버가 모두 같은 주소로 서버에 요청을 보낼 수 있도록 하기 위함
그러니까, 한 마디로 말하면 HTTP API에서 '피차 헷갈리지 않게 이 가이드에 맞춰서 소통해봅시다'라고 발전시킨 것이 REST API라고 볼 수 있습니다. (찾아보니 현업에서는 REST API의 네 가지 원칙을 철저히 지키기 어렵고, 그렇기 때문에 일반적으로 REST API라 하면 HTTP API를 칭하는 것이라 생각하면 된다고 합니다. 엄밀히 따지면 다르겠지만)
3. 알라딘 검색 API 뜯어보기
이제 본격적으로 북적북적에 사용된 알라딘 검색 API를 살펴봅시다. 이전 포스팅에서 살펴보았던 북적북적의 기능 프로세스와 API 사용 구조도는 아래와 같습니다. 북적북적에서는 알라딘 도서 검색 API를 활용하고 있으며, 도서명 검색 시 책 목록과 부가 정보들을 받아올 수 있습니다.
오늘은 위의 API가 구체적으로 어떤 형태를 가지고 있는지, 무엇을 요청하고 돌려받는지에 대해 조금 더 자세히 살펴보려고 합니다. 먼저 알라딘 도서검색 API를 살펴보면 아래와 같습니다.
북적북적에서 도서명을 검색하면, 해당 도서명이 parameter가 되어 서버에 요청이 전송됩니다. 상품검색 API의 요청 URL을 자세히 살펴보면 아래와 같습니다.
ttbkey=[TTBkey]
&Query=aladdin&QueryType=Title&MaxResults=10&start=1&SearchTarget=Book&output=xml&Version=20131101
*ttbkey는 알라딘 API를 사용하기 위해 발급받아야 하는 key로, 발급 절차를 마친 후 TTBkey 값을 입력해주면 됩니다.
이제 Query, QueryType, MaxResults, start, SearchTarget, output, Version이 각각 무엇을 뜻하는지 API 문서를 통해 알아봅시다.
Query는 검색어를 뜻함을 알 수 있습니다. 따라서 변수의 자료형은 문자열이 됩니다. 만약 Query=aladdin 이라면, 검색창에 '알라딘'이라 입력했음을 알 수 있습니다. 다음으로 QueryType를 살펴보면, Keyword/Title/Author/Publisher라는 변수 종류가 설정되어 있음을 볼 수 있는데, 위의 예시에서는 QueryType=Title이므로 '알라딘이라고 검색했는데요, 이 검색어의 종류는 제목입니다'를 의미함을 알 수 있습니다.
이어서 살펴보면, SearchTarget은 검색 대상 사이트를 의미함을 알 수 있습니다. 예시 URL에서는 SearchTarget=Book이라고 해두었으므로, '알라딘 도서판매 사이트에서 검색하겠다'를 의미합니다. 기본값이기 때문에 해당 파라미터를 생략한다면 자동으로 도서 판매 사이트에서 검색이 될 것 같습니다. 다음으로 Start는 검색 결과 시작페이지를 의미합니다. Start=1이라는 것은 검색 결과의 1페이지부터 응답으로 받겠다 라는 뜻입니다. MaxResults=10은 검색 결과 한 페이지당 최대 출력 개수를 의미하므로, 한 페이지에 10개의 검색 결과를 받겠다라는 뜻으로 이해할 수 있습니다. 마지막으로 output=xml은 요청에 대한 응답 결과를 xml형식으로 받겠다는 의미이며, Version=20131101은 알라딘 도서검색 API의 최신 버전(2013년)을 사용하겠다는 의미입니다.
따라서 ttbkey=[TTBkey]
&Query=aladdin&QueryType=Title&MaxResults=10&start=1&SearchTarget=Book&output=xml&Version=20131101 라는 요청 URL을 해석해보자면, "aladdin이라고 검색했을 때 검색되는 결과값을 돌려주세요. 그런데 검색어는 도서명이구요 알라딘 도서 몰에서 검색할 거예요. 검색 결과는 1페이지부터 볼 거구요, 한 페이지에는 10권씩 책이 출력되게 할 거예요. 응답값은 xml 형식으로 받아볼 거예요. 사용하는 API는 2013년 버전이에요!" 와 같다고 볼 수 있습니다.
다음으로는 응답 페이지를 살펴봅시다. 알라딘이 제공하는 예시 응답 페이지는 아래와 같습니다.
왼쪽은 xml 형식, 오른쪽은 js 형식의 응답 페이지입니다. xml과 js는 언어의 종류로, 간단히 설명하자면 위의 두 페이지는 같은 정보를 담고 있지만 다른 언어로 쓰여있다고 생각하시면 됩니다. 조금 더 가독성이 좋은 xml 페이지로 응답 parameter를 분석해 봅시다.
응답 parameter에 대한 내용이 기술되어 있는 부분을 살펴보면 아래와 같습니다.
위의 상세 기술 문서에 따라 응답 페이지를 살펴보면, 해당 응답 결과는 20131101ver API를 사용한 응답 결과이며, API 결과의 제목은 알라딘 검색결과 - aladdin , API 응답 페이지와 관련된 URL 주소는 http://www.aladin.co.kr/search/wsearchresult.aspx?KeyTitle=aladdin&SearchTarget=book&partner=openAPI, API 응답 페이지(해당 페이지)가 출력된 날짜는 2013년 11월 5일, 총 검색 결과 수는 203건, 페이지 수는 1페이지, 한 페이지에 18개의 책 출력, 조회한 쿼리(검색어)는 aladdin, 조회 카테고리는 전체(0)로 볼 수 있습니다.
지금 알라딘 홈페이지에서 aladdin이라는 검색어로 검색 시 결과페이지와 다른 책들이 출력됨을 확인할 수 있는데요, 위의 예시 문서가 출력된 날짜가 2013년이라는 점을 미루어 볼 때 2013년 당시 출력 결과를 예시 문서로 만들어 둔 것 같습니다.
이제 북적북적의 알라딘 API 활용 사례를 다시 한 번 살펴봅시다.
위의 사진은 북적북적 내부 검색창에 '일본어'를 검색했을 때의 화면인데요, 일본어 검색 시 '일본어'라는 도서명으로 검색된 책 목록들이 무한 스크롤로 모두 출력됩니다. 이 경우 아마 요청 쿼리는
tbkey=[북적북적 개발자가 받은 key값]
&Query=일본어&QueryType=Title&MaxResults=100&start=1&SearchTarget=All&output=xml/js 중 선호 형식&Version=최신API버전 이 될 것 같습니다.
책 목록을 모두 받아 무한 스크롤로 출력하기 때문에, 사실 MaxResults 값이 크게 상관은 없을 것 같습니다. 모두 받아와서 출력하는 것이니까요. 그렇다면 북적북적에서 '일본어'를 검색했을 때와, 알라딘 통합검색으로 '일본어'를 검색했을 때의 결과를 비교해 봅시다.
출력되는 결과가 같음을 확인할 수 있습니다. 정리하자면, 북적북적은 알라딘의 도서 검색 API를 활용해 '일본어'라는 검색어를 파라미터로 요청(Request)을 보냈고, 검색되는 결과값인 도서 목록들을 응답(Response)으로 받아왔고, 해당 결과값을 parsing해 보여주고 싶은 정보만 왼쪽과 같은 리스트 형태로 출력한 것입니다. 응답 결과를 parsing 후 출력할 때 북적북적의 내부 기준을 정해 출력했다면 오른쪽과 다른 결과가 출력되었을지도 모릅니다. (정확히 말하자면 응답 결과는 같지만 순서가 다르게 출력되었겠지요)
마치며..
모든 기능을 직접 구현하지는 않습니다.
이미 누군가 만들어 둔 프로세스를 사용하는 것을 API라고 합니다.
API는 HTTP라는 통신 규약을 따르고, 이 규약을 따르는 API를 HTTP API(대부분의 API, 넓은 범위)라고 합니다.
이 HTTP API에서, 주소와 메소드만으로도 요청 사항을 빠르고 명확하게 파악할 수 있도록 하는 가이드라인을 REST API 라고 합니다.
API의 요청 parameter와 응답 페이지는 API 문서에서 찾아볼 수 있습니다.
오늘의 과제 끝 😇
*참고 블로그
https://maliethy.github.io/posts/REST-API/
https://bentist.tistory.com/37
https://velog.io/@pm1100tm/HTTP%EC%9D%98-%ED%8A%B9%EC%A7%95-Request-%EC%99%80-Response
'Product Manager > 코드스테이츠 PMB14' 카테고리의 다른 글
| 스프린트 실행 과정에서 PO/PM의 역할은 무엇일까? (1) | 2022.10.18 |
|---|---|
| 북적북적과 알라딘 검색API 로 알아보는 서버, 백엔드, 프론트엔드 (완결) (0) | 2022.10.12 |
| 비즈니스에 따라 적합한 앱 유형은 무엇일까?(feat. 네이티브, 하이브리드, 모바일 웹, 웹앱) (0) | 2022.10.07 |
| 랜딩페이지의 뼈와 살을 분류해보자(feat. html, css, js, react) (0) | 2022.10.06 |
| 세상에서 가장 귀여운 기분일기, 하루콩을 분석해보자(feat.린 분석) (1) | 2022.09.30 |
