"나도 API 안다고!" 1: API 5분안에 이해하기

친해져 보자.. API...

API: "누구세요?"

 

IT 기획자라면 누구나 API 문서를 마주합니다. 기획자가 요청한 기획안은 API 문서에 반영된 후 개발이 이루어집니다. 솔직히 지금까지 "나는 개발자가 아니니까.." 하며 API 공부를 피해왔어요. 서버 개발자와 클라이언트 개발자 사이에서 왔다 갔다 하는 API 문서를 기획자가 이해하면 더 정확한 소통이 가능하기에 API의 개념부터 실습까지 잡고 가기로 했습니다.

 

API와 아직 친하지 않지만, 친해지면 좋은 기획자를 위해 공부한 내용을 간단하게 정리했습니다. IBM 클라우드 유튜브 채널의 API 교육 자료를 바탕으로 작성한 작성한 글이고, 다양한 API 중 REST API (웹 베이스 API)를 다룹니다.

 

 

API가 뭐예요?

API는 클라이언트와 서버가 통신하는 방식입니다. 클라이언트는 서버에 "이 메시지 보내줘", "로그인 해줘"와 같은 요청(request)을 보내고, 서버는 그에 맞게 응답(response)합니다.

 

API로 요청하고 응답한다

 

예를 들어 볼게요. 우리는 지금 재고가 있는 아이스크림 맛을 보여주는 앱을 개발 중입니다. 앱(클라이언트)은 API를 통해 서버에 필요한 정보를 요청합니다.

 

API는 URL의 형태로 되어 있습니다. API를 사용할 수 있는 URL을 부르면 서버에서 응답을 주죠.

 

"http://icecream.com/API/flavors" 

 

여기서 "com"까지는 서버주소로, 서버 컴퓨터가 위치한 곳의 주소입니다. 마지막 부분인 "API/flavors"는 우리가 API에서 "flavor(맛)" 리소스로 작업할 수 있음을 뜻합니다.

 

만약 URL이 이렇게 생겼다면요?

 

"http://icecream.com/API/users"

 

같은 서버이지만 가입자(users) 리소스로 작업할 수 있겠죠.

 

API의 두 축인 요청(request)과 응답(response)의 구조를 조금 더 쪼개서 볼까요.

 

 

클라이언트가 보내는 요청(Request)

 

헤더는 인증과 관련된 정보를 담습니다. 예를 들어, 네이버의 Open API를 사용할 때 인증 정보인 ID와 PW를 헤더에 적어야 합니다.

 

메소드는 동사와 같은 역할을 합니다. 생성(post), 읽기(get), 갱신(put), 삭제(delete)의 동작을 수행할 수 있습니다.

 

엔드 포인트는 리소스가 있는 곳을 뜻합니다. 위의 아이스크림 API URL에서 "/flavors"가 엔드 포인트입니다.

 

파라미터/바디로 데이터를 읽을 때 조건을 걸거나, 생성, 갱신할 데이터를 전달합니다.

 

 

서버가 보내는 응답(Response)

그렇게 해서 서버로부터 받은 response 데이터는 주로 JSON 형식입니다. JSON 데이터는 key : value로 보입니다.

 

{"flavor" : "딸기",

"price" : "3,500"}

 

 

아이스크림 앱 서비스 예시

ex 1. 재고가 있는 맛 찾기 (get flavors)

 

현재 재고가 있는 모든 맛을 알기 위해 정보를 읽는 "get" 메소드를 사용합니다. 맛 정보가 들어있는 위치인 "/flavors"를 엔드포인트에 적습니다. 그러면 서버에서 두 가지 맛이 있다고 응답하네요. ID 0에 해당하는 딸기와 ID 1에 해당하는 초코가 있습니다.

 

get flavors

 

ex 2. 품절된 초코 맛을 다른 맛으로 업데이트하기 (put flavor)

 

초코 맛의 인기가 폭발적이어서 품절되어 버렸어요. 초코를 민트초코로 바꿔야 됩니다. 그러면 엔드포인트에 초코 맛의 아이디인 1을 적고, 파라미터/바디에 업데이트할 맛의 정보를 적습니다. 서버의 응답에서 id 1번에 해당하는 맛이 민트 초코로 바뀌었다고 알려줍니다.

 

 

ex 3. 새로운 맛 추가하기 (post flavor)

 

엄마는 외계인이라는 새로운 맛이 추가됐습니다. 서버에도 새로운 맛의 정보를 추가해야겠죠? 추가하는 메소드인 post를 쓰고, 엔드포인트는 기존과 같이 /flavors로 두고, 새로운 맛의 정보를 파라미터/바디에 적었습니다. 그랬더니 response에 새로운 ID 2, 엄마는 외계인 맛이 추가되었다고 뜨네요.

 

post flavor

 

쉽게 이해됐죠? API와 JSON이라는 단어만 봤을 땐 머리가 아팠는데, 예시로 공부하니 이해하는 데 도움이 되었습니다.

 

머리로만 이해하는 공부와 손으로 직접 해보는 공부는 또 달라요. 다음 글에서 직접 API로 데이터를 가져오는 실습으로 API에 대한 이해도를 높여볼게요.

 

시리즈의 다음 글:

"나도 API 안다고!" 2: 재밌는 API 실습하기

 

---

<참고한 영상>

정확도가 떨어지지만 한국어 자막도 있습니다. IBM 교육 담당자가 REST API의 개념을 친절하게 잘 설명하는 영상입니다.

what is Rest API by IBM Cloud

 

*공부를 하며 정리한 내용으로, 정확하지 않은 내용에 대해 피드백을 주시면 귀 기울여 듣겠습니다. :)

 

오일남 할아버지는 API 썸네일