코드스테이츠 PMB 10기 | 개알못의 눈으로 살펴본 API

 

우리가 앱을 통해 어떤 기능 혹은 서비스를 이용할때, 뚝!딱!하고 해당 기능이 바로 실행되는 것처럼 보일 수 있지만

실은 특정 기능이 동작하기 위해서는 수많은 '요청'과 '응답'의 과정이 필요합니다.

 

<요청의 예>

"로그인 시켜줘"

"회원가입 시켜줘"

"메시지 삭제해줘"

...

 

위의 예시 이외에도 하나의 서비스를 구성하는 많은 동작들이 실행되기 위해서는 수많은 요청들이 존재할 것입니다. 이때 클라이언트와 서버가 원활하게 요청과 응답을 주고 받을 수 있도록 만든 체계를 API라고 합니다.

 

요청과 응답을 주고받기 위한 약속, API

 

API는 Application Programming Interface의 약자로, 클라이언트와 서버가 정보를 어떻게 주고 받을지에 대해 정해둔 '규칙들의 집합'입니다. 조금 더 자세히 설명하자면, '프로그램과 프로그램을 연결시켜주는 매개체'이자 '규격화된 서버'라고 할 수 있습니다. 

 

 

 

예를 들어, 우리가 백화점 식품관에서 음식을 주문한다고 가정해봅시다.

 

ㅋㅋ.....

 

만약 이 모든 메뉴를 하나의 조리장에서 처리하도록 구성한다면, 손님이 몰렸을 경우 서비스 제공에 문제가 발생할 수 있습니다. 

 

ㅋㅋ...

 

이를 해결하기 위해 백화점 식품관에 푸드코트를 마련하고, 취급하는 메뉴별로 전문화된 조리가 가능하도록 구성했습니다. 식품관에 방문한 고객의 다양한 요청에 대해 보다 효율적이고 신속하게 응답을 제공할 수 있도록, 각 메뉴를 담당하는 코너를 개설하여 요청과 응답의 프로세스를 보다 체계화 하였습니다.

 

이때 고객과 식품관의 상호작용을 원활하게 돕는 각각의 코너를 API라고 볼 수 있지 않을까 싶습니다.

 

그런데 이때 중요한 것은 원하는 음식(응답)을 제공받기 위하여 정확한 코너(주소)에 주문(요청)을 넣어야 한다는 것입니다. 돈가스를 주문하기 위해서는 사보텐텐에 주문을 넣어야하며, 마라탕을 주문하기 위해서는 마라왕국에 주문을 넣어야 합니다. 만약 돈가스 주문을 마라왕국에 넣게 되면 주문이 성립하지 않기 때문에 원하는 음식(응답)을 받을 수 없습니다.

 

API 도식화

 

출처=https://maily.so/grabnews/posts/b2341a

 

위와 마찬가지로 클라이언트와 서버간에도 요청과 응답을 빠르게 처리하기 위해, 기능(동작)별 서버를 구성하고 요청에 맞는 응답이 돌아올 수 있도록 규칙을 체계화했는데, 이를 API라고 합니다.

 

위와 같이 API를 통해 기능별로 분업화될 수 있도록 체계를 마련함으로써, 보다 간소화되고 빠른 프로세스 처리가 가능해집니다.

 

---

 

 

이처럼 많은 주문을 효율적으로 처리할 수 있도록 기능별로 분업화된 규칙을 마련했으나, 또 다른 문제가 존재합니다. 사람마다 주문하는 방식이 다를 수 있다는 것인데요.

 

예를 들어, 푸드코트에 간 세 친구가 AI 알바생에게 돈가스를 주문한다고 또 가정해봅시다...(가정 좀 그만해...) 

 

 

 

<세 친구의 요청>

 

돈가스 주문할게요.

돈가스 주세요.

돈가스 하나요.

 

모두 돈가스를 주문하기 위한 요청이지만 세 친구가 모두 다른 방식으로 주문하고 있기 때문에, 과연 AI 알바생이 동일한 응답을 내놓을지 알 수가 없습니다.

 

이때 요청과 응답을 주고받기 위해 필요한 통일된 대화 규칙, 그것을 'REST API'라고 합니다.

 

REST & RESTful(REpresentational State Transfer) API

 

위 사례에서도 알 수 있듯 API를 아무리 잘 설계한다고 하더라도, 요청 방식이 통일되지 않는다면 응답이나 유지보수에 어려움이 있을 수 있습니다. 이러한 문제를 해결하기 위해 마련한 통일된 일련의 규칙을 REST API라고 합니다. 그리고 REST 아키텍처의 제약 조건을 준수하는 API를 RESTful API 라고 합니다.

 

• REST: HTTP 통신에서 클라이언트가 서버의 리소스에 접근하는 방식을 규정한 아키텍처
• RESTful API: REST 아키텍처의 제약 조건을 준수하는 서비스 API

 

이때, 어떤 자원에 대한 *CRUD 요청을 Resource(URI)와 Method로 표현하여 특정한 형태로 전달합니다.

 

REST API의 구성요소

• 자원(Resource) - URI
  - 모든 자원은 Server에 존재하며, 고유한 ID를 지닌다.
• 행위(Verb) - HTTP Method
  - HTTP 프로토콜의 Method를 사용한다.
  - GET, POST, PUT/PATCH, DELETE
• 표현(Representations) - 페이로드
  - 클라이언트의 요청에 대한 서버의 적절한 응답을 의미한다.
  - 하나의 자원은 JSON, XML, TEXT, RSS 등 여러 형태의 Representation으로 나타낼 수 있다.
  - 대부분 JSON의 형태로 주고 받는다.

 

RESTful API의 요청과 명령의 종류

자원(Resource)에 대한 행위(Verb)는 다음과 같은 Method로 표현합니다.

• C(Create) : 타임라인에 사진을 '올리는' 요청 > POST
• R(Read) : 사진을 '불러오는' 요청 > GET
• U(Update) : 사진을 '바꾸는' 요청 > PUT(전체) / PATCH(일부)
• D(Delete) : 사진을 '지우는' 요청 > DELETE

 

---

 

Open API

 

Open API는 누구나 사용할 수 있도록 공개된 API입니다. API의 플랫폼 기능 혹은 콘텐츠를 외부에서 웹 프로토콜(HTTP)로 호출하여 사용할 수 있게 개방한 것으로, 이를 활용하면 유용한 기능을 빠르게 구현할 수 있다는 장점이 있습니다.

 

그렇다면 카카오, 네이버, 구글 등 수많은 기업에서는 기업의 고유 자산이라고 할 수 있는 API를 무료로 공개하는 이유가 무엇일까요? 

 

이는 결국 사업가치와 연관이 되어 있습니다. 무료로 API를 공개함으로써 기업이 취할 수 있는 이득이 더 크기 때문입니다. 기업은 API를 개방함으로써 자사의 기능을 더욱 많이 활용할 수 있도록 유도하여 시장 점유율을 확보할 수 있습니다.

 

그리고 저는 API를 통해 요청과 응답이 어떻게 이루어지는지 살펴보기 위해, 카카오 개발가이드 페이지의 오픈 API를 참고했습니다. 

 

 

---

 

<다음 책 서비스 - 책 검색 API 뜯어보기>

 

<책 검색 API 설명>

다음 책 서비스에서 질의어로 도서 정보를 검색합니다. 원하는 검색어와 함께 결과 형식 파라미터를 선택적으로 추가할 수 있습니다. 응답 바디는 meta, documents로 구성된 JSON 객체입니다.

 

아래는 카카오의 책검색 API 개발 가이드를 캡처한 화면입니다. 앞서 살펴본 바와 같이 요청(Request)과 응답(Response)으로 나뉘어져 있음을 알 수 있었습니다.

 

 

요청하기(Request)

 

Request(요청)에 포함되어야 할 내용

• method (전송 방식)
  GET, POST, PUT/PATCH, DELETE
• url: (전송 주소)
  어떤 데이터를 요청할거야?
• data: (보낼 데이터) 
  자료 요청에 필요한 추가 정보 (JSON 형식으로 데이터를 전송함)

 

카카오 책검색 API는 다음과 같이 URL과 Parameter로 구분되어 있습니다. 

 

 

<URL>

 

 

위 이미지를 통해 가장 먼저 확인 가능한 정보는 method(:GET) 입니다. 이 정보를 통해 서버에 어떤 요청을 보냈는지 파악할 수 있습니다.

 

Host 값으로 나타나있는 'dapi.kakao.com'은 컴퓨터가 있는 위치를 의미합니다.

 

Authorization은 접근 권한을 의미합니다. REST API를 요청할 때 HTTP 헤더에 해당 정보를 추가하여 인증 받을 수 있습니다. 이는 API를 요청한 계정의 소유자를 확인하는데 필수적인 절차입니다.

 

 

<Parameter>

 

method를 보낼 때 포함되는 변수를 의미합니다. 클라이언트는 서버에 요청을 보낼 때 data를 함께 전송해야 하는데요. 이때 data에 어떤 파라미터(변수)가 포함되어야 하는지를 아래의 표를 통해 확인할 수 있습니다.

 

아래 표를 살펴보면 'query'가 필수값으로 설정되어 있음을 알 수 있습니다. 책 검색 API이기 때문에, 검색을 원하는 질의어(query)를 필수적으로 입력해야만 서버에서 응답하는 구조로 설계되어 있음을 추정할 수 있습니다. 

 

<요청 예시>

 

Request 예시 자료를 살펴봅니다. 

 

• GET 형식의 method를 전송합니다.
• url 변수에는 데이터를 요청하기 위한 url을 작성합니다.
  http://dapi.kakao.com/v3/search/book?target=title&query="미움받을 용기"
  -> 데이터를 요청할 도메인입니다. 카카오 책 검색 API를 나타냅니다.
  -> target 파라미터에 title(책 제목)을 전달합니다.
  -> 필수값으로 설정되어 있던 query 파라미터에 검색할 질의어("미움받을 용기")를 전달합니다.
• Header 영역에 발급받은 REST API KEY를 넣어줍니다.

 

 

 

응답하기(Response)

 

다음 책 검색 API의 Response(응답)는 다음과 같이 meta와 documents로 구분되어 있습니다.

 

 

meta는 웹 서버로 보내는 요청과 요청 데이터를 설명하는 정보로, HTTP 헤더에 포함되어야 합니다.

 

 

Documents에는 응답에 포함될 세부 항목들이 표시되어 있습니다. 책 검색 API이기 때문에 도서 정보와 관련된 내용이 주를 이룹니다.

 

<응답 예시>

 

 

가장 상단에 '200'이라는 응답값을 확인할 수 있습니다. 해당 숫자는 클라이언트의 요청에 대한 응답으로, 요청 사항이 잘 처리되었음을 의미합니다. 그리고 요청한 데이터는 모두 JSON 형태로 출력되고 있음을 알 수 있습니다.

 

JSON은 JavaScript Object Notation의 약어로, 데이터를 저장하거나 전송할 때 이용되는 DATA 교환 형식의 일종입니다. 

이 형식은 사람이 읽고 쓰기에 용이하며, 기계가 분석하고 생성함에도 용이합니다.

 

지난주 과제에 JSON 형식과 응답값에 대해 이해한 내용을 간략하게 작성한 바 있으므로, 해당 내용을 첨부하겠습니다.

 

<지난 과제>

 

---

 

오늘은 문과생의 입장에서 클라이언트와 서버가 요청과 응답을 주고받는 과정을 살펴보고, API는 어떤 역할을 하는지 이해해 보고자 했습니다. 컴퓨터가 인간의 언어를 이해할 수 있다면 좋으련만 그것은 불가하기에, 각 프로그램간 상호작용을 원활히 하기 위해서는 보다 체계화된 방법이 필요하다는 것을 알 수 있었습니다. 

 

그 중에서도 오늘 살펴본 API 문서를 통해 특정 기능이 실행되기 위하여 어떤 요청과 응답의 과정이 필요한지 하는지, 이때 필요한 정보는 무엇인지 개략적으로 파악할 수 있었습니다. PM으로서 API를 직접 개발하지는 않겠지만, API 문서를 읽고 이해할 수 있다면 스스로 업무의 진행상황을 예측해 볼 수 있기에 개발자와의 협업을 원활하게 하는 하나의 자산이 될 수 있지 않을까 싶습니다. 지금은 개념에 구멍이 너무 많기 때문에 추후 더욱 학습해보는 것으로...

 

위 글은 개린이의 눈으로 이해한 바를 서술했기에, 사실과 다른 점이 있을 수 있습니다. 혹 제가 잘못 이해한 부분이 있다면, 피드백 남겨주시면 감사하겠습니다 :D 

 

참고자료

 

https://docs.solapi.com/authentication/api-key

API Key 인증 방식 - SOLAPI

 

https://pronist.dev/146

'REST' 를 보다 'RESTful' 하게 API 만들기

https://meetup.toast.com/posts/92

REST API 제대로 알고 사용하기 : NHN Cloud Meetup

http://www.incodom.kr/RestFul_API

RestFul API - 인코덤, 생물정보 전문위키

https://velog.io/@dev_bomdong/TIL-CRUD%EC%99%80-HTTP-%EC%9A%94%EC%B2%AD-%EB%A9%94%EC%86%8C%EB%93%9C

CRUD와 HTTP 요청 메소드

https://velog.io/@somday/RESTful-API-%EC%9D%B4%EB%9E%80

RESTful API 이란

https://maily.so/grabnews/posts/b2341a

API와 API 서버 개념 정리하기

https://brunch.co.kr/@businessinsight/65#comment

서버가 API를 뭐..? 개발자의 외계어 쉽게 이해하기