IT 기획자를 위한 API 기획 체크리스트: 개발자 회의 전에 꼭 확인할 질문

이 글의 핵심 요약

API의 기본 개념을 이해했다면, 이제 중요한 것은 실무에 적용하는 것입니다. 이번 글에서는 IT 기획자가 API 회의 전에 확인해야 할 질문, HTTP 메서드, 상태코드, 오류 메시지, 기획서 작성 예시를 정리합니다.

이전 글 먼저 보기

API의 기본 개념이 아직 낯설다면 아래 글을 먼저 읽어보세요. 이번 글은 1편의 개념을 바탕으로 실무 체크리스트를 다룹니다.

👉 이전 글: IT 기획자를 위한 API란? 개발자 회의 전에 꼭 알아야 할 기본 개념

지난 글에서는 API를 IT 기획자 관점에서 정리했습니다. API는 화면이 서버에 데이터를 요청하고, 서버가 그 결과를 화면에 돌려주는 약속입니다.

그런데 API 개념을 이해하는 것과 실제 기획서에 반영하는 것은 또 다른 문제입니다. 회의에서는 이런 질문들이 튀어나옵니다.

“이건 GET인가요, POST인가요?”
“저장 성공 후 어떤 화면으로 이동하나요?”
“로그인 만료 시 메시지만 보여 주나요, 로그인 화면으로 보내나요?”
“목록이 없을 때 빈 화면 처리는 어떻게 하나요?”
“중복 클릭하면 주문이 두 번 생성될 수 있는데 막아야 하나요?”

이 질문들은 모두 API 기획과 연결됩니다. API 기획은 개발자의 영역처럼 보이지만, 사실 기획자가 먼저 정리해야 할 업무 조건이 많습니다. 화면 뒤에 숨어 있던 데이터들이 회의실 책상 위로 우르르 올라오는 순간입니다.

API 기획은 어디서부터 시작할까?

API 기획은 기술 문서 작성에서 시작하지 않습니다. IT 기획자에게 API 기획은 화면의 동작을 데이터 흐름으로 바꿔 보는 것에서 시작합니다.

API 기획의 시작점
이 화면에서 사용자가 어떤 행동을 하고, 그 행동 때문에 서버와 어떤 데이터를 주고받아야 하는지 정리하는 것입니다.

예를 들어 “배송지 저장” 기능을 기획한다고 해보겠습니다. 화면에는 이름, 휴대폰 번호, 주소, 기본 배송지 여부가 있습니다. 사용자가 저장 버튼을 누르면 이 정보가 서버에 전달되어야 합니다.

이때 기획자는 아래 내용을 정리해야 합니다.

저장 버튼은 언제 활성화되는가?
필수 입력값은 무엇인가?
휴대폰 번호 형식이 틀리면 어떻게 안내하는가?
기본 배송지로 설정하면 기존 기본 배송지는 어떻게 바뀌는가?
저장 성공 후 목록으로 이동하는가, 현재 화면에 남는가?
저장 실패 시 사용자가 입력한 값은 유지되는가?

이런 내용이 정리되어야 개발자는 API 요청값, 응답값, 예외 처리를 설계할 수 있습니다.

기획자 관점 핵심

API 기획은 엔드포인트 이름을 정하는 일이 아닙니다. 화면에서 발생하는 사용자 행동, 데이터 조건, 성공과 실패 상황을 정리하는 일입니다.

GET·POST·PUT·DELETE를 기획 업무로 이해하기

API 회의에서 자주 나오는 단어 중 하나가 HTTP 메서드입니다. GET, POST, PUT, DELETE 같은 표현이 대표적입니다. 기획자가 이것을 개발 문법처럼 외울 필요는 없습니다. 기능의 성격으로 이해하면 충분합니다.

HTTP 메서드	기획자식 이해	기능 예시	기획서 표현 예시
GET	데이터를 조회한다	공지사항 목록 조회, 상품 상세 조회	화면 진입 시 목록을 조회한다.
POST	새 데이터를 등록하거나 처리를 요청한다	회원가입, 주문 생성, 댓글 작성	저장 버튼 클릭 시 입력 정보를 등록한다.
PUT	기존 데이터를 수정한다	회원 정보 수정, 배송지 수정	수정 완료 버튼 클릭 시 변경된 정보를 저장한다.
DELETE	기존 데이터를 삭제한다	게시글 삭제, 관심상품 삭제	삭제 버튼 클릭 시 해당 항목을 삭제한다.

개발자가 최종적으로 어떤 메서드를 사용할지는 개발 설계에 따라 달라질 수 있습니다. 하지만 기획자는 해당 기능이 조회인지, 등록인지, 수정인지, 삭제인지 명확히 구분해야 합니다.

기획자가 기억할 기준
GET은 가져오기, POST는 만들기나 처리 요청, PUT은 수정하기, DELETE는 삭제하기로 이해하면 됩니다.

예를 들어 “관심상품” 기능을 기획한다면 다음처럼 기능 성격을 나눌 수 있습니다.

사용자 행동	기능 성격	기획자가 정리할 내용
관심상품 목록 진입	조회	목록 정렬 기준, 노출 항목, 빈 화면 문구
관심상품 추가	등록	중복 추가 가능 여부, 성공 메시지
관심상품 메모 수정	수정	수정 가능 조건, 저장 후 화면 처리
관심상품 삭제	삭제	삭제 확인 팝업, 삭제 후 목록 갱신 여부

상태코드는 사용자 안내 정책과 연결된다

HTTP 상태코드는 API 요청 결과를 숫자로 표현한 값입니다. 개발자는 상태코드를 통해 성공과 실패를 구분합니다. 기획자는 상태코드를 사용자 안내 정책과 연결해서 봐야 합니다.

상태코드	기획자 관점의 의미	사용자 메시지 예시	화면 처리 예시
200	정상 처리	정상적으로 처리되었습니다.	데이터 노출 또는 성공 화면 이동
400	요청값이 잘못됨	입력한 정보를 다시 확인해 주세요.	입력 화면 유지, 오류 항목 강조
401	로그인이 필요함	로그인 후 이용해 주세요.	로그인 화면으로 이동
403	접근 권한이 없음	접근 권한이 없습니다.	이전 화면 이동 또는 안내 화면 노출
404	요청한 대상을 찾을 수 없음	요청한 정보를 찾을 수 없습니다.	목록으로 이동 또는 빈 화면 노출
500	서버 오류	일시적인 오류가 발생했습니다. 잠시 후 다시 시도해 주세요.	재시도 버튼 또는 공통 오류 화면 노출

상태코드에서 중요한 것은 숫자 자체가 아닙니다. 사용자가 다음에 무엇을 해야 하는지 알 수 있도록 안내하는 것입니다.

아쉬운 메시지 예시
오류가 발생했습니다.

더 나은 메시지 예시

로그인 시간이 만료되었습니다. 다시 로그인해 주세요.
휴대폰 번호 형식이 올바르지 않습니다.
해당 게시글은 삭제되었거나 접근 권한이 없습니다.
일시적인 오류가 발생했습니다. 잠시 후 다시 시도해 주세요.

같은 오류라도 사용자에게 보여 줄 문구와 개발자가 확인할 로그는 다릅니다. 사용자 메시지는 친절하고 구체적이어야 하고, 개발 로그는 원인 파악이 가능해야 합니다. 이 둘을 구분하는 것이 좋은 API 오류 정책의 시작입니다.

오류 메시지는 기획자가 꼭 챙겨야 한다

API 오류는 개발자만 처리하는 영역이 아닙니다. 사용자에게 보이는 메시지는 서비스 경험과 직접 연결됩니다. 그래서 기획자는 오류 상황을 화면 정책으로 정리해야 합니다.

오류 메시지를 정리할 때는 아래 세 가지를 기준으로 보면 좋습니다.

기준	확인할 질문	예시
원인	사용자 입력 문제인가, 권한 문제인가, 서버 문제인가?	휴대폰 번호 형식 오류, 로그인 만료, 서버 오류
안내	사용자가 이해할 수 있는 문구인가?	입력한 정보를 다시 확인해 주세요.
다음 행동	사용자가 무엇을 하면 되는가?	다시 로그인, 입력값 수정, 잠시 후 재시도

오류 메시지 작성 공식
상황 설명 + 사용자가 할 수 있는 다음 행동

예를 들어 “저장 실패”라고만 쓰면 사용자는 무엇을 해야 할지 알 수 없습니다. 하지만 “네트워크 연결이 불안정합니다. 연결 상태를 확인한 후 다시 시도해 주세요.”라고 쓰면 다음 행동이 분명해집니다.

API 오류 메시지는 작은 문구처럼 보이지만, 실제 운영에서는 문의량과 직결됩니다. 애매한 오류 메시지는 고객센터로 날아가는 종이비행기가 됩니다.

API 회의 전 기획자가 준비해야 할 질문

API 회의에 들어가기 전 아래 질문을 준비하면 좋습니다. 이 질문들은 개발자를 압박하기 위한 것이 아니라, 기획서가 다시 돌아오는 일을 줄이기 위한 안전장치입니다.

API 기획 회의 체크리스트

이 기능은 어떤 사용자 행동에서 시작되는가?
화면 진입 시 API가 호출되는가, 버튼 클릭 시 호출되는가?
요청값으로 반드시 필요한 항목은 무엇인가?
선택값은 무엇이고, 값이 없을 때 기본값은 무엇인가?
응답값에는 어떤 데이터가 포함되어야 하는가?
목록 데이터라면 정렬, 필터, 페이징 기준이 필요한가?
데이터가 없을 때 빈 화면 문구는 무엇인가?
로그인이 만료되면 어떤 화면으로 이동하는가?
권한이 없는 사용자는 어떤 메시지를 보게 되는가?
중복 요청이 발생하면 어떻게 처리하는가?
저장 성공 후 현재 화면에 남는가, 다른 화면으로 이동하는가?
오류 메시지는 공통으로 처리하는가, 기능별로 다르게 처리하는가?
개인정보나 민감정보는 마스킹이 필요한가?
첨부파일이 있다면 용량, 확장자, 보관 기간 정책이 있는가?
운영자가 데이터를 수정하거나 재처리할 수 있어야 하는가?

이 체크리스트를 기준으로 회의하면 개발 중간에 다시 확인해야 하는 이슈를 줄일 수 있습니다. 특히 요청값, 응답값, 오류 처리, 권한 조건은 초반에 정리할수록 좋습니다.

기획서에 API 내용을 적는 방법

기획자가 API 명세서를 개발자처럼 상세하게 작성할 필요는 없습니다. 하지만 화면정의서나 기능정의서에 API와 연결되는 정보를 남겨 두면 협업이 훨씬 쉬워집니다.

기획서 항목	작성 예시
기능명	주문 목록 조회
사용자 행동	마이페이지 > 주문 내역 메뉴 클릭
호출 시점	주문 내역 화면 진입 시
요청 조건	로그인 사용자, 조회 기간, 주문 상태, 페이지 번호
응답 데이터	주문번호, 주문일자, 상품명, 결제금액, 배송상태
정렬 기준	최근 주문일순
빈값 처리	주문 내역이 없습니다. 문구 노출
오류 처리	로그인 만료 시 로그인 화면으로 이동
권한 조건	본인 주문 내역만 조회 가능

위와 같이 정리하면 개발자는 API 설계 방향을 잡기 쉽고, 기획자는 화면과 데이터의 연결 관계를 명확히 설명할 수 있습니다.

기획자의 목표
API를 완벽하게 설계하는 것이 목표가 아닙니다. 개발자가 API를 설계할 수 있도록 화면, 데이터, 조건, 예외를 빠짐없이 전달하는 것이 목표입니다.

API 기획 실무 예시

이제 실제 예시로 정리해 보겠습니다. 아래는 “배송지 저장” 기능을 API 기획 관점으로 정리한 예시입니다.

항목	기획 내용
기능명	배송지 저장
사용자 행동	배송지 입력 후 저장 버튼 클릭
필수값	수령인 이름, 휴대폰 번호, 주소, 상세 주소
선택값	배송 요청사항, 기본 배송지 설정 여부
유효성 검사	휴대폰 번호 형식 확인, 필수값 누락 확인
성공 처리	배송지가 저장되었습니다. 메시지 노출 후 배송지 목록으로 이동
실패 처리	입력값 오류 시 해당 항목 하단에 안내 문구 노출
중복 처리	저장 버튼 연속 클릭 시 중복 저장되지 않도록 버튼 비활성화
기본 배송지 정책	새 배송지를 기본 배송지로 설정하면 기존 기본 배송지는 해제

이 정도로 정리하면 개발자는 어떤 데이터가 필요한지, 어떤 조건을 검증해야 하는지, 성공과 실패 상황을 어떻게 처리해야 하는지 이해하기 쉽습니다.

기획서 문장 예시

사용자가 배송지 저장 버튼을 클릭하면 필수 입력값을 검증한 후 배송지 정보를 저장한다. 필수값이 누락되거나 휴대폰 번호 형식이 올바르지 않을 경우 해당 입력 항목 하단에 오류 문구를 노출한다. 저장 성공 시 “배송지가 저장되었습니다.” 메시지를 노출하고 배송지 목록 화면으로 이동한다.

기획서에는 이처럼 사용자의 행동, 데이터 조건, 검증 기준, 성공 처리, 실패 처리를 함께 작성하는 것이 좋습니다. 그래야 화면정의서가 단순한 그림 설명에서 실제 개발 가능한 문서로 바뀝니다.

마무리

API 기획은 어렵게 보이지만, IT 기획자 관점에서는 명확합니다. 화면에서 사용자가 어떤 행동을 하고, 그 행동으로 어떤 데이터를 요청하거나 저장하며, 성공과 실패 상황을 어떻게 처리할지 정리하면 됩니다.

개발자처럼 API 명세를 모두 작성할 필요는 없습니다. 하지만 기획자는 아래 내용을 놓치지 않아야 합니다.

기능의 성격이 조회, 등록, 수정, 삭제 중 무엇인지
요청값과 응답값에 어떤 데이터가 필요한지
데이터가 없을 때 어떤 빈 화면을 보여 줄지
오류가 발생했을 때 어떤 메시지를 보여 줄지
로그인과 권한 조건은 어떻게 처리할지
저장 성공 후 어떤 화면으로 이동할지

이 내용만 잘 정리해도 개발자 회의의 품질이 달라집니다. API는 개발자의 코드 안에만 있는 것이 아닙니다. 기획서의 문장, 화면의 조건, 사용자 메시지 속에도 숨어 있습니다.

결국 좋은 API 기획은 “개발자가 알아서 해주세요”를 줄이고, “이 화면은 이런 조건으로 동작해야 합니다”를 명확히 만드는 일입니다. 회의실의 안개를 걷어내는 작은 헤드램프 같은 역할입니다.

FAQ

Q1. IT 기획자가 HTTP 메서드까지 알아야 하나요?

개발자처럼 깊게 알 필요는 없습니다. 다만 GET은 조회, POST는 등록이나 처리 요청, PUT은 수정, DELETE는 삭제 정도로 이해하면 개발자와의 회의가 훨씬 쉬워집니다.

Q2. API 기획 체크리스트에서 가장 중요한 항목은 무엇인가요?

요청값, 응답값, 오류 처리, 권한 조건입니다. 이 네 가지가 정리되지 않으면 개발 단계에서 재질문이 자주 발생합니다.

Q3. 상태코드는 기획서에 꼭 적어야 하나요?

모든 상태코드를 기획서에 적을 필요는 없습니다. 다만 로그인 만료, 권한 없음, 데이터 없음, 서버 오류처럼 사용자 화면에 영향을 주는 경우에는 메시지와 화면 처리를 정리하는 것이 좋습니다.

Q4. API 오류 메시지는 누가 정해야 하나요?

기술적인 오류 구분은 개발자가 정리하지만, 사용자에게 보여 줄 안내 문구는 기획자가 정리하는 것이 좋습니다. 사용자가 다음 행동을 이해할 수 있도록 메시지를 설계해야 합니다.

Q5. API 기획서를 따로 만들어야 하나요?

조직마다 다릅니다. 별도 API 기획서를 만들 수도 있고, 화면정의서 안에 요청 조건, 응답 데이터, 오류 처리, 권한 조건을 함께 정리할 수도 있습니다. 중요한 것은 개발자가 필요한 정보를 빠짐없이 확인할 수 있게 작성하는 것입니다.

이 블로그 검색

AI야, 기획 아이디어 줄래?