API 명세를 기획자가 읽는 법 — 개발자랑 같은 그림 그리기

"이거 명세 보고 말씀해주세요"

기획 회의에서 개발자가 API 명세 링크를 툭 던지며 "이거 보고 말씀해주세요"라고 하면, 코드를 안 다루는 기획자는 순간 막막해집니다. 낯선 표와 영어 필드가 잔뜩인 문서를 보면 "이건 개발 영역"이라며 덮어두기 쉽습니다. 하지만 API 명세 읽는 법은 코딩과 별개입니다. 몇 가지 구조만 알면, 기획자도 충분히 읽고 심지어 누락을 먼저 잡아낼 수 있습니다.

이 글에서는 코드를 한 줄도 몰라도 되는 선에서, 기획자가 API 명세에서 무엇을 봐야 하는지 네 가지로 정리합니다. 목표는 하나입니다 — 개발자와 같은 그림을 그리는 것.

API 명세란 — 프런트와 백엔드가 주고받는 계약서

API는 화면(프런트엔드)과 서버(백엔드)가 데이터를 주고받는 통로입니다. API 명세는 그 통로의 사용 설명서이자 계약서입니다. "이 주소로, 이런 걸 보내면, 이런 게 돌아온다"를 미리 약속해 둔 문서죠.

실무에서 명세는 보통 OpenAPI(스웨거) 문서나 노션·표 형태로 전달되는데, 형식이 무엇이든 읽는 요령은 같습니다. 기획자에게 이 문서가 중요한 이유는 분명합니다. 화면에 "포인트 잔액"을 보여주기로 기획했는데 응답에 잔액 필드가 없으면, 그 화면은 못 만듭니다. 명세를 미리 읽으면 이런 누락을 개발 착수 전에 발견할 수 있습니다. 코드가 아니라 "무엇이 오가는가"만 보면 됩니다.

기획자를 위한 API 명세 읽는 법 — 핵심 4가지

명세가 아무리 길어도, 기획자가 볼 곳은 네 군데로 압축됩니다.

1. 엔드포인트 — 무엇을, 어떻게

엔드포인트는 "어떤 주소로 무슨 동작을 하는가"입니다. 보통 메서드 + 경로로 적혀 있습니다.

• GET /users/123 — 조회 (가져오기)
• POST /orders — 생성 (새로 만들기)
• PUT /users/123 — 수정 (통째로 교체)
• DELETE /orders/456 — 삭제

기획자는 여기서 "이 기능이 조회인가 생성인가"만 알면 됩니다. 예를 들어 "주문하기"는 생성(POST), "주문 내역"은 조회(GET)입니다.

2. 요청 — 무엇을 넣어야 하나

요청(Request)은 화면이 서버에 보내는 값입니다. 파라미터 목록에서 각 항목의 이름·타입·필수 여부를 봅니다. 여기서 기획자가 챙길 것은 "이 값을 화면 어디서 받아 채우지?"입니다. 필수 항목인데 화면에 입력란이 없으면, 그 화면은 기획이 덜 된 것입니다.

3. 응답 — 무엇이 돌아오나

응답(Response)은 서버가 돌려주는 값입니다. 기획자에게 가장 중요한 부분입니다. 화면에 뿌릴 데이터가 전부 응답에 있는지 확인합니다. "상품명·가격·재고"를 보여주기로 했는데 응답에 재고가 없다면, 개발 전에 추가를 요청해야 합니다.

4. 상태 코드 — 성공과 실패

상태 코드는 요청의 결과 신호입니다. 숫자 세 자리로 옵니다.

• 200 — 성공
• 400 — 잘못된 요청 (값이 빠졌거나 형식 오류)
• 401 — 인증 안 됨 (로그인 필요)
• 404 — 없음 (해당 데이터 없음)
• 500 — 서버 오류

기획자는 여기서 "실패했을 때 화면에 뭘 보여줄지"를 정합니다. 400이면 "입력을 확인하세요", 500이면 "잠시 후 다시 시도하세요" 같은 문구를 미리 기획해 두면 개발이 매끄럽습니다.

표로 보는 요청·응답 예시

말로만 보면 추상적이니, 실제 명세의 축약 형태를 보겠습니다. "주문 조회" API라면 대략 이런 모습입니다.

구분	필드	타입	의미
요청	orderId	문자열	조회할 주문 번호(필수)
응답	productName	문자열	상품명
응답	price	숫자	결제 금액
응답	status	문자열	주문 상태(결제완료/배송중 등)

응답이 실제로 오는 모습은 이렇게 생겼습니다.

[code lang="json"] { "productName": "무선 이어폰", "price": 89000, "status": "배송중" } [/code]

기획자는 이 중괄호를 코드로 읽을 필요가 없습니다. "이름: 값"의 목록으로 보면 됩니다 — 상품명은 "무선 이어폰", 가격은 89000. 화면에 필요한 게 다 있는지만 눈으로 훑으면 충분합니다.

명세를 읽을 때 기획자가 던져야 할 질문

명세를 다 이해하려 하기보다, 아래 질문 몇 개만 던져도 협업의 질이 확 올라갑니다.

• 화면에 보여줄 데이터가 응답에 전부 있는가? 없으면 어디서 채우나?
• 필수 요청 값을 화면에서 다 받고 있는가?
• 실패(400/401/500) 시 사용자에게 무슨 문구를 보여줄까?
• 목록이 많으면 **페이지 나눔(페이징)**은 어떻게 되나?
• 이 요청이 결제·주문처럼 중요한 동작이면, 두 번 눌러도 안전한가? (이 부분은 멱등성 글에서 다룹니다.)

왜 기획자가 API 명세를 읽어야 하나

결국 핵심은 같은 그림 그리기입니다. 기획자가 명세를 읽지 않으면, 화면 기획과 실제 데이터가 어긋난 채로 개발이 시작되고, 그 간극은 QA 단계에서야 터집니다. 명세를 미리 읽으면 그 사고를 설계 단계에서 막습니다. 이건 기획자와 개발자의 온도차를 좁히는 스모크 테스트와도 같은 맥락입니다 — 문제를 늦게 발견할수록 비용이 커집니다.

기획자에게 필요한 건 코딩 실력이 아니라, "무엇이 오가는가"를 읽는 눈입니다. 그 눈만 있으면 개발자와 대화가 통하고, 회의가 짧아집니다.

코드가 아니라 데이터를 읽는 것

API 명세 읽는 법의 핵심을 다시 한 줄로 줄이면 이렇습니다. 코드를 읽는 게 아니라, 엔드포인트·요청·응답·상태 코드라는 네 개의 데이터 흐름을 읽는 것입니다. 이 네 가지만 짚으면 명세의 90%는 이해한 셈이고, 개발자와 같은 그림을 그릴 수 있습니다.

다음 회의에서 개발자가 명세 링크를 던지거든, 덮어두지 말고 이 네 곳부터 펼쳐 보세요. "여기 응답에 재고 필드가 빠진 것 같은데요?" 한마디가, 며칠 뒤의 재작업을 막습니다.