진짜 쉬운 API 설명: 온라인 비즈니스 세상에서 API 모르는 사람 없게 해 주세요!

API 설명 전, 이해를 돕기 위해 한 가지만 짚고 넘어가자. 당신은 매크로, 자동화, 크롤링이란 단어를 아는가? 온라인 비즈니스에 조금이라도 관심이 있었다면, 아니 비즈니스가 아니더라도 특정 사이트의 정보를 자동으로 복붙하고 싶은 사람이라면 한 번쯤은 들어봤을 것이다. 매크로, 크롤링은 복붙하는 나의 존재를 사이트에서는 알 수 없다는 특징이 있다. 반면, API는 상호 합의된 데이터 교환 방식이라는 차이가 있다. 소수 몇 명하고만 합의할 것인지, 신청하는 모든 이들에게 다 합의해 줄 것인지 그 제공 범위는 조금 다를 수 있겠다. 쉽게 말해 API는각자 다른 서비스 제공자들끼리 보다 효율적으로 데이터를 주고받기 위해 만들어진 일종의 규칙이다.

 

음식점 사례로 알아보는 API 개념 원리!

API 개념을 정말 쉽고 간편하게 이해하기 위해 음식점 실제 사례를 가져와 봤다. 선릉역에 정말 맛있는 청국장 집이 하나 있다. 메뉴는 청국장, 제육볶음, 오징어볶음이 있는데, 특이한 방식으로 주문이 이뤄진다. 여기서 잠깐 논리 퀴즈 들어간다.

• “제육볶음 하나, 청국장 두 개, 오징어 한 개” = “2, 1, 1”
• “청국장 한 개, 오징어볶음 한 개, 제육볶음 한 개” = “1, 1, 1”
• “오징어 셋, 청국 둘” = “2, 0, 3”
• “오징어 다섯, 청국장 둘, 제육볶음 셋” = “?”

 

눈치 챘는가? 이 가게에는 특이한 주문 프로세스가 있다. 손님이 어떤 순서로, 어떤 형태로 주문하는지와는 무관하게 점원은 [청국장], [제육볶음], [오징어볶음] 순서대로 숫자를 외친다. 예를 들면 이렇다.

• 손님 A
  • 손님 → 점원: 청국장 하나, 제육 하나, 오징어 하나
  • 점원 → 주방: 하나, 하나, 하나~
• 손님 B
  • 손님 → 점원: 오징어 셋, 청국장 둘
  • 점원 → 주방: 둘, 없고, 셋~
• 손님 C
  • 손님 → 점원: 오징어 하나, 제육 하나, 청국장 둘
  • 점원 → 주방: 둘, 하나, 하나~

 

주문이 잘 들어 갔다면, 이후에는 어떤 일이 벌어질까? 주방에서 음식을 만들고 → 점원을 통해 → 손님에게 서빙 될 것이다. 만약, 재료가 소진되었다면? 주방에서는 점원에게 재료가 다 떨어졌다 알려 줄 것이고, 점원은 손님에게 다른 것을 주문하도록 안내할 것이다.

지금까지 일어난 일을 화살표 순서대로 정리해 보자면, 손님 → 점원 → 주방 → 점원 → 손님 → 이후 반복이다. API에서는 이것을 요청(Request)과 응답(Response) 이라고 부른다.

 

음식점 사례로 이해하는 API 용어 정의!

API 요청(Request)과 API 응답(Response)

먼저, 손님과 점원의 대화를 살펴보자. 손님이 점원에게 주문하면 요청, 점원이 최종적으로 음식을 내오면 응답이다. 이 대화의 특징은 자연어라는 점이다. 가끔씩(!) 주문 오류가 발생하기도 한다. 메뉴를 실수로 잘못 말하거나, 잘 말했더라도 실수로 다른 음식이 나오는 상황을 상상해 보자.

다음으로, 점원과 주방의 대화를 살펴보자. 점원이 주방에 메뉴를 외치면 요청, 주방에서 점원에게 음식을 만들어주면 응답이다. 이 대화의 특징은, (물론 이는 API를 이해하기 위해 극단적으로 든 예시지만,) 정해진 규칙으로 메뉴 개수만을 외친다는 것인데, 이를 통해 오류가 상대적으로(손님과 자연어 대화 보다는) 낮다는 특징이 있다. 아래 그림을 통해서 조금 더 이해해 보자.

 

OpenAPI, PrivateAPI, PartnerAPI, PublicAPI? 이게 다 뭐지?!

API 공개 범위에 따라 구분한 개념이라고 보면 된다. 음식점을 상상하면서 비교해 보자.

OpenAPI는 누구에게나 열린 소통이라는 뜻이다. 바로 와닿지 않을 수 있는데, 위 음식점 사례에서 "손님과 점원" 간의 소통에서 사용하는 API라고 볼 수 있다. 누구든지 와서 주문해서 먹을 수 있는 일반적인 음식점 상황인 것이다. 한편, PrivateAPI는 비공개 소통이라는 뜻이다. 음식점 사례에서 "점원과 주방" 간의 소통에서 사용하는 API라고 볼 수 있다. 직관적으로는, 외부에 알려지지 않은 API라고 이해하면 된다.

PartnerAPI는 일부 사용자에게 공개된 소통이라는 뜻이다. 점심 예약을 VIP 고객에게만 받는 상황을 상상해 보자. PublicAPI는 OpenAPI와 유사하게 느껴질 수 있겠는데, 일반적으로 공공재 성격을 가진 OpenAPI를 표현한다.

 

요청(Request)의 종류 두 가지! GET과 POST!

일반적으로 API는 HTTP 통신 방식을 따르는데, HTTP가 무엇인지 궁금한 사람들을 위해 다른 글을 준비하고 있다. API에서는 딱 두 가지만 기억하면 충분하다.

• GET
  • Read
  • 정보를 단순히 읽기만 하는 상황
  • ex. 음식점에서 메뉴판 정독하는 사람, 와인 리스트 정독하는 사람, 벽에 붙은 원산지 표 살펴보는 사람 등
• POST
  • Create
  • 정보를 직접 입력, 수정, 가공 등 후속 행동을 하는 상황
  • ex. 주문 넣기, 반찬 리필, 현금 영수증 신청하기, 신용카드로 결제하기 등
• 참조. HTTP 통신 방식 네 가지: POST, GET, PUT, DELETE

 

실제로 API를 한 번이라도 써 본 사람은 위 내용으로 바로 이해가 될 텐데, 아직 사용해 보지 않은 사람은 공공기관에서 제공하는 API를 한 번 사용해 보면 좋겠다. 다른 글에서 실제로 API를 날려보는 실습을 해보려 한다.