API문서 먼저 검토하기

기획자가 그런것도 봐야해요?

Feb 26. 2025

왜 API문서를 먼저 봐야 할까? 볼 수 있다는 가정하에 내용을 미리 알면 나한테 이득이 되기 때문이다. 지금도 그렇지만 5년전을 생각하면 직접 API문서를 보는 기획자/PM은 매우 드물었다. Twillio 나 Stripe같은 기업이 읽기 좋은 API문서의 기준을 세운 이래로 많은 사람들이 이 분야에 공을 들이기 시작했고, 이제는 많은 기업들이 누구나 파악하기 쉬운 API문서를 생산한다. 그래서인지 이제는 간혹 이를 활용하는 기획자 동료도 있다. 내부 API문서가 있다면 새로 개발해야하는지 등 의사결정을할때 개발팀에 묻지않고 직접 의사결정하는데 판단근거로 활용할 수 있다. 외부의 API문서를 미리 본다면 제약사항을 미리 확인하고 터무니없는 기획을 하지 않도록 선을 정하는데 활용할 수 있다. 이 외에도 API문서를 업무에 활용하는 다양한 방법들이 있다. 그래서 우리는 이를 보는 방법을 배워서 미리 읽어봐야 한다.

API는 무엇일까? Application Programming Interface의 약자다. 어플리케이션(응용 프로그램)을 만들기위한 프로그래밍 규약(접점) 이라는 뜻이다. 개발자가 요리사라고 가정하고 어플리케이션이 하나의 요리라고 생각했을때 ‘반재료’정도에 해당하는것이 API라고 볼수있다. 감칠맛을 내기위해 매번 닭과 각종 야채 버섯등을 넣고 끓일 수 도있지만, 미리 만들어둔 치킨스톡을 사용하면 예측가능한 맛을 정확히 빠른시간에 구현할수 있다. 요리하기전에 냉장고에 어떤 재료가 있는지 확인하는 과정이 API문서를 확인하는것에 비할수 있을테고, 없으니 새로 만들어야한다는 개발자들의 요청은 집에 재료가 없으니 마트가서 사오든지 원재료들로 새로 육수를 내야한다 정도로 이해할 수 있다.

왜 이런것들이 필요할까? 적당히 시간만 있으면 다 만들수 있는거 아닐까? 라고 생각할수도 있다. 소프트웨어 개발에서 원칙적으로 안되는건 없지만 어렵고 비효율적이고 불가능한것들은 분명 존재한다. 주변을 둘러보면 개발자들도 백엔드/프론트앤드 나눠져있는걸 많이 봤을것이다. 소프트웨어가 동작하는건 결국 0과 1의 디지털 신호다. 그런데 매번 디지털신호까지 직접 짤 수 없으니 특정 기능을 하는 기초적 명령들, 예를들면 더하기 빼기 같은 사칙연산들을 미리 만들어서 모아둔다. 그럼 그 기초 명령들을 가지고 프로그래밍 언어를 만들고 그 언어는 복잡한 과정을 거쳐서 “특정 지역범위안에 있는 음식점 목록을 보여줘”같은 API하나를 만드는데 사용된다. 마치 태평양에 수없이 깔려있는 해저케이블의 단면을 보면 작은 가닥들의 수많은 선들이 하나로 모여있는 형태와 비슷하다.

출처: 위키백과, https://m.ppomppu.co.kr/new/bbs_view.php?id=freeboard&no=7950076

API문서를 보지 않고 요청하거나 기획서를 작성하면 엉뚱한 요청을 하기 쉽다. 게시판을 기획한다고 가정해보자. 글 목록을 보여주는 보통의 게시판에는 글 번호, 제목, 작성자, 작성일 그리고 경우에 따라 조회수나 추천수정도를 보여준다. Gamification(게임화)가 유행이라기에 모든 사용자들에게 활동을 많이할수록 포인트를 주고 레벨을 부여하는 기획을 했다. 게시글 목록에서도 해당 사용자의 레벨을 보여주고싶다. 그래서 요청을했더니 그건 안된다고한다. 왜 안될까? API 문서를 살펴보면 그 이유를 알 수 있다. 현재 게시글 목록을 가져오는 API는 다음과 같은 응답 구조를 가지고 있다.

여기서 문제는 게시글 정보에 작성자의 ID나 상세 정보가 포함되어 있지 않다는 점이다. 단지 이름만 문자열로 포함되어 있을 뿐이다. 사용자 레벨 정보는 별도의 사용자 정보 API를 통해 가져와야 하는데, 이를 위해서는 사용자 ID가 필요하다.

이런 상황에서 게시글 목록에 사용자 레벨을 표시하려면 두 가지 접근법이 있다. 백엔드에서 API를 수정하여 게시글 정보에 작성자 ID와 레벨 정보를 추가 하거나 프론트엔드에서 게시글 목록을 가져온 후, 각 작성자의 정보를 별도로 요청할 수도 있다.

첫 번째 방법이 사용자 경험 측면에서는 좋지만, 기존 API 구조를 변경해야 하므로 개발 리소스가 더 필요하다. 두 번째 방법은 추가 API 호출이 발생하여 성능면에서 우려될 수 있다. 기획자가 API 문서를 미리 검토하고 기획했다면, 이런 제약사항에 대해 대안을 마련할 수 있었을 것이다. 예를 들어, 게시글 작성자 정보를 더 풍부하게 표시하는 별도의 UI 컴포넌트를 기획하거나, 아니면 레벨 표시를 게시글 상세 페이지에만 노출하는 방향으로 기획할수도 있었다. 운이좋다면 게시판 목록을 조회하는 API에 여유로 뚫어둔 필드가 있어서 이부분을 활용할 수 있는 경우도 있을 수 있다.

API의 기본개념

최근 몇년간 많은 개발자들을 흡수한 토스의 API문서를 한번 보자.

회사마다 문서 디테일한 문서 구성방식은 다를 수 있지만, 기본 골격은 위 예시와 같은 형태를 취한다. 이 API가 어떤 기능을 하는지에 대한 설명, 요청할때 보내는 값들, 그럼 답변해주는 값들로 구성되어있다. 토스처럼 예시를 보여주는 경우도 있으며 사이트 내에서 직접 호출해볼 수 있는 기능을 제공하는 경우도 있다. 문서의 양이 많고 무엇을 봐야할지 몰라 겁먹을 수도 있다. 그러나 쫄지않고 바라보면 이해할 수 있다. 이 문서가 작성된 개발자들의 목표는 이 기능을 사용할 사람들이 이해하고 잘 쓰도록 하는것이다. 다소 투박해도 목적이 분명한만큼 필요한 정보는 모두 담겨있다.

요청과 응답 이해하기

결국 API 문서는 ‘어떤 값을 주면 우리가 특정 기능을 수행해서 이걸 해줄게‘ 를 풀어서 쓴 것이다.

여기서 무얼 주면 에 해당하는게 요청(Request)다. 여기엔 어떤 방식으로 호출해야할지(GET/POST/PUT/DELETE) 보낼때 필수로 당신이 누구고 필요한 경우 인증정보를 어떻게 보내야 하는지(Header) 마지막으로 어떤 값들을 보내줘야 수행이 가능한지(Body)로 구성된다.

이 요청이 서버로 잘 도착했다는 가정하에 응답(Response)에는 요청을 잘 처리했는지에 대한 상태코드(200, 400, 등)와 처리한 내용, 요청한 값 자체(Body)와 이에대한 부가정보들(Header)이 담기게 된다.

알아둬야 할 개념

- 파라미터, 매개변수등의 표현은 호출시에 보내야 할 값들을 이야기합니다. 그 API 파라미터는 뭐가 들어가요? 라고 물어보면 Request에 있는 필수값들을 알려주면 된다.

- JSON, XML등은 주고받을 때 쓰는 데이터들의 형식을 말합니다. 응답은 JSON으로 오나요? 라고 개발자가 묻는다면 네 그럴거에요 정도로 답하면 된다.

- 최초 연동을 하기 위한 필수 요소에는 해당 서버의 API키 발급, 해당 서버에서 요청을 받을 수 있도록 허용하는 방화벽 오픈, 우리 서버에서 요청이 나갈 수 있도록 하는 방화벽 오픈이 선행되어야 하며 이는 개발자에게 요청하기 전에 미리 작업해둘 수 있다. 이를위해 우리 서버의 IP주소 대역을 알아두면 좋고. API 키는 협력사를 통하거나 개발자 페이지에서 미리 발급받을 수 있다.

- 요청이 잘 되었는지 확인하는 Response의 응답 코드는 매우 많지만 자주 쓰이는 코드는 다섯가지 정도 이다. 200 OK(잘 받았다), 400 Bad Request(뭔가 잘못요청했다), 403 Forbidden(너는 여기 권한 없다), 404 Not Found(주소를 잘못입력했다), 500 Internal Server Error(우리서버가 뭔가 문제가있다). 400번대는 우리가 잘못한거고 500번대는 그쪽이 잘못했다고 파악하면 좋다.

- 인증 방식에는 OAuth, JWT 등이 있는데 그런게 있다는정도만 알아두면 좋다.

검토할때 중요한 점검 포인트

제일 중요한건 필수/선택 파라미터가 어떤것인지 파악하는 것이다. 원하는 바를 얻기 위해 필수로 필요한 값들이 우리에게 있는지 알아야 그다음 단계로 넘어갈 수 있다. 또 그들의 응답값이 내가 기획한 바를 달성하는데 충분한지도 점검해 봐야한다. 날씨정보를 조회했을때 습도와 미세먼지 지수에 따른 생활친화적 메시지를 기획했는데 미세먼지 농도 관련 정보는 API에서 주고있지 않다면 처음부터 구현이 불가능하다고 볼 수 있다. 또 성능관련 제약도 파악해야한다. 피할수 없는 경우 요청을 대상에 대해 n번 보내야 하는 경우가 있고 n^2 번 보내야 하는 경우도 흔하게 생긴다. 이때 이 API가 어느정도 까지 속도와 몇 번의 호출까지 받아주는지 확인하고 구조적으로 호출회수를 줄일 수 있는지 파악하면 좋다.