회의 막히기 전, 숫자보다 화면부터 봅니다
API 문서 요청 응답 예시는 개발자만 보는 자료처럼 보이지만, PM이나 기획자도 기본 구조는 알아야 회의가 편해집니다. 요청은 “무엇을 보낼지”, 응답은 “무엇을 받을지”를 적은 약속이라고 보면 돼요.
처음부터 JSON 문법을 완벽히 외울 필요는 없습니다. 화면에서 필요한 값이 요청에 들어가는지, 서버가 돌려주는 값이 화면에 쓸 수 있는지, 실패했을 때 어떤 오류가 나오는지만 보면 됩니다.
이 글은 API 문서 요청 응답 예시를 비개발자 기준으로 풀어봅니다. 개발자에게 덜 묻고, 물어보더라도 더 정확하게 묻는 것이 목표입니다.
회의에서 막히는 지점은 대개 문법이 아닙니다. “이 값이 화면 어디에 쓰이지”, “실패하면 사용자는 뭘 보지” 같은 연결이 흐려질 때 대화가 길어져요. 그래서 문서를 코드가 아니라 화면 흐름으로 읽어야 합니다.
처음 보는 문서라도 겁먹을 필요는 없습니다. 화면, 값, 오류만 나누면 꽤 읽힙니다. 처음엔 개발 용어를 전부 이해하려고 달려들지 않아도 됩니다.
잠깐 정리하면, 회의 전에 세 줄이면 됩니다
- API 문서 요청 응답 예시는 화면과 서버가 주고받는 약속을 보여줍니다.
- 요청값은 보내는 재료, 응답값은 화면에 다시 그릴 결과입니다.
- 오류 코드는 누구 책임을 따지기보다 어디서 막혔는지 보는 신호입니다.
- 기능 범위가 애매하면 기능정의서 작성방법과 같이 보면 좋습니다.
- 성공, 실패, 빈값을 나눠 보면 QA에서 다시 묻는 일이 줄어들어요.
- 회의 전에는 화면에 필요한 값과 오류 문구만 표시해도 충분히 도움이 됩니다.
- 문서가 길면 전체를 다 읽기보다 요청, 응답, 오류 부분만 먼저 접어두면 훨씬 편해요.
API 문서 요청 응답 예시, 요청값 체크가 먼저입니다
요청값은 사용자가 화면에서 입력하거나 선택한 값과 연결돼요. 로그인이라면 아이디와 비밀번호, 검색이라면 검색어와 필터, 주문이라면 상품 번호와 수량이 요청에 들어갈 수 있어요.
기획자가 먼저 볼 것은 필드 이름보다 화면의 행동입니다. 사용자가 버튼을 눌렀을 때 어떤 값이 서버로 가야 하는지 떠올리면 문서가 훨씬 덜 무서워요.
예를 들어 검색 화면이라면 요청에는 검색어, 정렬 방식, 페이지 번호가 들어갈 수 있습니다. 여기서 페이지 번호가 빠지면 “더보기”나 페이지 이동이 이상해질 수 있어요.
문서를 볼 때는 “이 값이 화면 어디에서 왔지?”라고 생각하면 편합니다. 출처가 안 보이는 요청값은 기획서나 화면 설계 쪽으로 다시 돌아가야 해요.
응답값은 화면의 빈칸에서 바로 보입니다
응답값은 서버가 다시 보내주는 결과입니다. 목록 화면이라면 제목, 날짜, 상태, 작성자 같은 값이 응답에 들어갈 수 있어요. 상세 화면이라면 더 많은 정보가 필요하겠죠.
API 문서 요청 응답 예시에서 응답값을 볼 때는 화면의 빈칸을 채운다고 생각하면 편합니다. 화면에는 가격이 있는데 응답에는 가격이 없으면 개발자는 어디선가 값을 더 받아와야 합니다.
반대로 응답에는 값이 있는데 화면에서 쓰지 않는 경우도 있습니다. 그 값이 나중에 필요한지, 지금은 숨겨둔 것인지, 아예 빠져도 되는지 정리하면 좋아요.
이때 요구사항 정의서 작성법에서 말하는 사용자 행동과 결과가 같이 맞아야 합니다. API는 화면 밖의 약속이지만, 출발점은 결국 사용자 흐름이에요.
값 세 묶음 체크 포인트
아래는 실제 서비스 문서가 아니라 구조를 이해하기 위한 예시입니다. 핵심은 중괄호가 아니라 어떤 값이 오가느냐예요.
| 구분 | 예시 값 | PM이 볼 점 |
|---|---|---|
| 요청 | userId, page | 화면에서 보내는 값인지 |
| 응답 | name, status | 화면에 필요한 값인지 |
| 오류 | 400, 401, 500 | 사용자 안내가 필요한지 |
요청·응답 예시는 이렇게 세 묶음으로 나누면 됩니다. 요청, 응답, 오류입니다. 한 번에 보면 복잡하지만, 쪼개면 회의에서 물어볼 말이 선명해져요.
예를 들어 응답에 status가 있다면 그 상태가 “대기”, “완료”, “실패”처럼 화면 문구로 바뀌는지 확인해야 합니다. 개발자는 값 이름을 보고, 기획자는 사용자가 보는 말로 바꿔야 합니다.
API 문서 요청 응답 예시를 읽다가 숫자와 영어가 많아 보여도 당황할 필요 없습니다. 화면에 필요한 값인지, 실패했을 때 사용자가 알아야 하는지부터 보면 돼요.
400과 500, 탓하기 전 위치 체크
오류 코드는 누구 잘못인지 따지는 표가 아닙니다. 어디서 막혔는지 알려주는 신호에 가깝습니다. 400번대는 요청 쪽을 먼저 보고, 500번대는 서버 쪽 문제를 의심하면 됩니다.
API 문서 요청 응답 예시에는 성공 응답만 있으면 부족합니다. 로그인 실패, 권한 없음, 없는 데이터, 서버 오류 같은 상황도 같이 있어야 QA가 편해요.
이미 숫자 해석이 헷갈린다면 API 문서 오류 코드 이해를 먼저 보면 좋습니다. 400, 401, 403, 404, 500을 크게 나눠두면 API 문서가 훨씬 읽힙니다.
기획자가 개발자에게 물어볼 말은 이 정도면 충분합니다. “오류가 나면 보여줄 사용자 문구”, “다시 시도 버튼 필요 여부”, “로그인 만료 시 이동 위치”처럼 짧게 적어두면 돼요.
개발자에게 묻기 전, 질문을 줄이는 법
API 문서 요청 응답 예시를 보고 바로 질문하기 전에 네 가지를 먼저 체크하세요. 질문이 정리되면 개발자 답변도 빨라져요.
- 요청값이 화면 입력값과 맞는지 봅니다.
- 응답값이 화면에 필요한 정보와 맞는지 확인합니다.
- 오류 상황별 사용자 문구가 필요한지 표시합니다.
- 테스트할 케이스를 성공, 실패, 빈값으로 나눕니다.
프로젝트 일정과 연결된다면 구글 스프레드시트 WBS에 API 확인 업무를 따로 넣어두는 것도 좋습니다. API 확인은 개발 막판에 발견하면 꽤 아픕니다.
API 문서 요청 응답 예시는 개발자 문서이기도 하지만, 기획자에게는 화면이 빠뜨린 값을 찾는 도구입니다. 이렇게 보면 읽는 부담이 확 줄어듭니다.
자주 묻는 질문, 여기서 막힙니다
개발자가 아니어도 봐야 하는 범위
전부 깊게 볼 필요는 없습니다. 다만 화면에 필요한 값이 요청과 응답에 있는지는 봐야 합니다. API 문서 요청 응답 예시를 조금만 알아도 “이 값은 어디서 오는지”를 더 정확하게 확인할 수 있습니다. 회의에서는 필드 이름보다 화면에서 어디에 쓰이는지 먼저 말하면 대화가 덜 꼬여요. 모르는 타입은 개발자에게 넘겨도 괜찮습니다.
JSON 문법을 몰라도 읽는 순서
처음에는 중괄호나 쉼표보다 값의 의미를 보면 됩니다. API 문서 요청 응답 예시에서 userId, status, page 같은 값이 화면 어디에 쓰이는지 연결하면 문법은 천천히 따라옵니다. 모르는 타입이 나오면 개발자에게 “화면 표시용인지, 저장용인지”만 물어도 충분합니다. 처음부터 문법 공부로 들어가면 오히려 더 멀어져요. 화면 기준으로 보면 부담이 확 줄어듭니다.
오류 응답 예시가 필요한 순간
성공만 있으면 사용자가 실패했을 때 무엇을 봐야 하는지 정하기 어렵습니다. API 문서 요청 응답 예시에 오류 응답이 있으면 QA, 문구, 재시도 버튼, 로그인 만료 처리를 미리 정할 수 있습니다. 오류 문구를 나중에 붙이면 화면 흐름이 다시 흔들릴 수 있어요. 개발이 끝난 뒤 발견하면 수정 범위도 커집니다. 그래서 실패 케이스는 초반에 같이 적어두는 편이 좋습니다.
화면과 서버 사이 약속 체크
API 문서 요청 응답 예시는 어려운 개발 문서가 아니라 화면과 서버가 서로 약속한 종이입니다. 요청은 보내는 값, 응답은 받는 값, 오류는 막힌 지점을 알려주는 표시입니다.
처음부터 모든 필드를 외우려 하지 않아도 됩니다. 화면에 필요한 값이 있는지, 실패했을 때 사용자에게 보여줄 말이 있는지, 개발자에게 확인할 질문이 남았는지만 보면 충분해요.
이 주제로 막힌 예시가 있다면 요청값, 응답값, 오류 코드 중 어디에서 헷갈렸는지만 남겨주세요. 그 지점부터 다음 글에서 더 쉽게 쪼개보겠습니다. 실제 문서의 한 줄만 있어도 같이 읽는 기준을 만들 수 있습니다.
