기획자가 API를 꼭 이해해야 하는 이유
직접 쓰진 않지만, 제대로 읽고 판단해야 한다
“API 연동 규격서에 POST로 기재돼 있는데 GET 방식 아닌가요?”
“방금 호출한 결제 API 오류 응답이 오는데, A사에 확인 부탁드립니다”
기획자가 된 뒤 처음엔 이 말들이 무슨 뜻인지도 몰랐습니다.
하지만 업무를 하다 보면 차차 익혀지더군요.
비록 기획자가 직접 규격서를 작성하진 않더라도,
그 안에 어떤 데이터가 오가고, 언제 요청이 발생하는지를 이해하고 있어야, 제대로 된 기획서를 쓸 수 있습니다.
API, 그게 도대체 뭐예요?
API는 Application Programming Interface의 약자예요.
“서로 다른 시스템끼리 주고받는 대화 양식”이라고 보면 됩니다.
라멘집에서 주문서 쓰는 것과 똑같아요
“돈코츠 라멘 하나 주세요. 면은 꼬들하게, 계란은 2개, 육수는 진하게요.”
이걸 주방에 넘긴다고 쳐요.
그럼 주방은 이 주문서에 맞게 음식을 만들어서 결과를 내놓죠.
바로 이 ‘주문서’가 API 요청이고,
주방에서 나온 결과가 API 응답입니다.
A시스템에서 B시스템에 “이거 해줘”라고 요청할 때,
그걸 형식화해서 쓰는 게 바로 API인 거죠.
회사에서는 이렇게 씁니다
우리 회사 빌링 시스템에 카카오페이 결제를 붙이기로 했다고 해볼게요.
사용자가 결제 버튼을 누르면 그 순간부터 시스템 간 대화가 시작됩니다.
우리 시스템이 카카오페이에 POST /payments 같은 API를 호출
“이 고객이 10,000원 결제하려고 해요”라고 요청
카카오페이는 “결제 성공했어요!“라는 응답을 보냅니다.
이 모든 주고받는 과정을 ‘어떻게’, ‘무슨 데이터로’, ‘언제’ 주고받는지 정의한 문서가 바로 API 명세서(API 연동 규격서)입니다.
명세서? 규격서? 이게 다 뭐야?
사람마다, 회사마다 용어가 조금씩 달라요.
어떤 조직은 API 명세서라고 부르고 또 어떤 곳은 연동 규격서, 혹은 인터페이스 정의서라고 부릅니다
결론은 같습니다.
“우리가 언제, 어떤 데이터로 요청을 보내고, 어떤 응답을 받아야 하는지를 정의한 문서”
부르는 건 자유,
중요한 건 내용을 정확히 읽고 해석할 수 있느냐입니다.
기획자=이해하고, 검토하고, 수정하는 역할
규모가 있는 조직에서는
API 명세서는 보통 개발자가 작성합니다.
기획자는 보통
문서를 검토하고,
논리적으로 맞는지 체크하고,
누락된 케이스나 문제 가능성을 피드백합니다.
즉, 기획자는 이 문서의 감독자이자 통역사예요.
“이게 실제 사용자 흐름과 맞는가?”
“기획 의도와 일치하는가?”
그걸 판단하는 사람이 바로 기획자입니다.
기획자가 API 명세서를 볼 때 꼭 짚어야 할 질문 3가지
API 명세서를 펼쳤을 때, 다음 세 가지 질문만 떠올리면 됩니다.
1. 어떤 기능이 호출되는가?
예: 로그인? 결제? 주문 확인?
명세서 상의 엔드포인트(예: POST /users/login)에서 기능 흐름을 읽을 수 있어요.
2. 어떤 데이터를 주고받는가?
요청값(Request)과 응답값(Response)이 어떤 형식인지 봐야 해요. 어떤 값이 필수인지, 화면에 어떤 데이터를 표시할지 이걸 기반으로 판단합니다. 필수값 누락이나 타입 오류는 실제 서비스에서 큰 장애가 되기 때문에 특히 중요합니다.
3. 실패하면 어떻게 처리할 것인가?
에러코드(400, 500)와 에러 메시지를 통해 실패 상황이 명확히 정의돼 있어야 해요. 사용자에게 어떤 안내 문구를 띄울지, 시스템에 어떤 로그가 남아야 할지도 여기서 파악됩니다.
그리고 한 가지 더! 흐름과 UX는 함께 봐야 합니다
기획자는 명세서를 ‘읽는 사람’이 아니라
시나리오를 상상하고 흐름을 설계하는 사람이에요.
“이 버튼을 누르면 어떤 API가 몇 번 호출되고, 어떤 순서로 응답이 올까?”
“이 흐름이 사용자 경험과 자연스럽게 맞물릴까?”
“실패할 경우 어떤 문구가 노출되고, 개발자나 운영팀엔 어떤 알람이 가야 할까?”
마무리하며
기획자는 개발자가 아니고, 코드도 쓰지 않습니다.
하지만 시스템 사이에서 어떤 데이터가 오가고, 어떤 규칙으로 연결되는지를 ‘이해’ 하지 못하면, 기획이 무너집니다.
API를 이해한다는 건, 단순히 명세서를 읽는 게 아니라 시스템 간 대화 흐름을 머릿속에 그릴 수 있게 된다는 뜻이에요.
처음엔 단어 하나하나가 낯설고, 흐름도 복잡하게 느껴졌지만 저도 하나씩 겪고 나서야 ‘아, 이런 구조였구나’ 하고 이해가 되기 시작했어요.
명세서를 보며 “이게 어떤 요청이고, 어떤 응답이 오지?” 정도만 짚을 수 있어도 기획서의 깊이는 확실히 달라집니다.
완벽히 알지 않아도 괜찮아요.
지금처럼 한 줄씩 해석해 보며 익숙해지는 게, 충분히 좋은 출발이니까요.
