DEVELOPMENT
화면 개발 전에 API 명세를 먼저 맞춰야 하는 이유
화면 개발 전에 API 명세를 먼저 맞춰야 하는 이유
API 명세는 백엔드만을 위한 기술 문서가 아닙니다. 화면에 필요한 데이터와 상태, 오류 처리 방식을 개발 전에 합의하면 프론트엔드와 백엔드가 같은 기준으로 작업할 수 있고 불필요한 재작업도 크게 줄일 수 있습니다.
API 명세는 백엔드만을 위한 기술 문서가 아닙니다. 화면에 필요한 데이터와 상태, 오류 처리 방식을 개발 전에 합의하면 프론트엔드와 백엔드가 같은 기준으로 작업할 수 있고 불필요한 재작업도 크게 줄일 수 있습니다.
API 명세는 화면과 데이터를 연결하는 약속입니다
프론트엔드 개발은 API가 완성되기 전에도 시작할 수 있습니다. 디자이너가 만든 화면을 기준으로 임시 데이터를 넣고, 버튼을 연결하고, 로딩 화면까지 구현할 수 있습니다. 문제는 이 임시 데이터에 개발자의 예상이 자연스럽게 섞인다는 점입니다.
화면에서는 주문 상태를 orderStatus로 가정했는데 실제 API는 status를 반환할 수 있습니다. 가격을 숫자로 예상했지만 통화 기호가 포함된 문자열로 전달되거나, 항상 존재할 것으로 생각한 배송 완료일이 null로 돌아올 수도 있습니다.
각각은 작은 차이처럼 보입니다. 하지만 실제 연동 단계에서 이런 차이가 여러 화면에 쌓이면 프론트엔드는 이미 완성한 컴포넌트를 다시 수정해야 하고, 백엔드는 화면의 요구에 맞춰 응답 구조를 재검토해야 합니다. QA 과정에서는 데이터 문제인지 화면 문제인지 확인하는 시간까지 필요해집니다.
API 명세는 이러한 예상의 차이를 개발 전에 발견하는 기준입니다. 여기에는 단순히 주소와 필드 이름만 적는 것이 아니라 다음 내용이 포함되어야 합니다.
어떤 화면과 기능에서 사용하는 API인지
요청할 때 필요한 값과 각 값의 형식
성공했을 때 반환되는 데이터 구조
필수 값과 선택 값,
null이 가능한 값로딩·빈 결과·오류 상태의 처리 기준
인증과 사용자 권한에 따른 차이
목록의 페이지네이션과 정렬 방식
좋은 API 명세를 만들면 기획 문서, UI 디자인, 프론트엔드 코드와 백엔드 로직이 하나의 기준으로 연결됩니다.
정상적인 데이터뿐 아니라 화면의 모든 상태를 함께 정의합니다
화면을 설계할 때는 데이터가 정상적으로 도착한 순간을 중심으로 생각하기 쉽습니다. 하지만 사용자가 실제로 만나는 화면에는 로딩, 빈 결과, 접근 제한, 네트워크 오류처럼 훨씬 다양한 상태가 존재합니다.
필드명과 데이터 타입을 먼저 맞춥니다
주문 상세 화면에 주문 번호, 결제 금액, 배송 상태와 배송 완료일이 필요하다고 가정해보겠습니다. API 명세에는 각 값이 단순히 “있다”는 사실보다 구체적인 규칙이 필요합니다.
orderId: 문자열인지 숫자인지totalPrice: 원 단위 정수인지 소수점이 포함된 값인지status: 사용할 수 있는 상태가 무엇인지deliveredAt: 아직 배송되지 않았다면null이 되는지items: 상품이 없을 때 빈 배열인지 필드 자체가 생략되는지
데이터 타입과 nullable 규칙이 빠져 있으면 프론트엔드는 임의의 방어 코드를 추가하게 됩니다. 사람마다 다른 방식으로 예외를 처리하면 같은 서비스 안에서도 화면마다 결과가 달라질 수 있습니다.
상태값은 화면 표현과 연결합니다
status: "processing"이라는 값이 단순히 API에 존재하는 것으로 끝나서는 안 됩니다. 화면에서 어떤 문구와 색상으로 보여줄지, 사용자가 주문을 취소할 수 있는지, 다음 단계는 무엇인지까지 연결해야 합니다.
예를 들어 주문 상태를 다음과 같이 합의할 수 있습니다.
pending: 결제 확인 중, 취소 가능paid: 결제 완료, 배송 준비 중shipping: 배송 중, 배송 조회 가능delivered: 배송 완료, 구매 확정 가능cancelled: 취소 완료, 재주문 가능
이렇게 상태값과 사용자 행동을 함께 정의하면 기획자, 디자이너와 개발자가 같은 의미로 상태를 이해할 수 있습니다.
오류 응답도 하나의 화면 상태입니다
오류가 발생했을 때 단순히 “오류가 발생했습니다”라고 표시하는 것으로 충분하지 않은 경우가 많습니다.
주문이 존재하지 않는 경우, 로그인이 만료된 경우, 해당 주문을 볼 권한이 없는 경우는 사용자가 취해야 할 행동이 각각 다릅니다. 따라서 상태 코드와 오류 코드, 사용자에게 보여줄 메시지의 역할을 나누어야 합니다.
401: 다시 로그인하도록 안내403: 접근 권한이 없음을 설명404: 주문을 찾을 수 없으며 목록으로 이동500: 잠시 후 다시 시도할 수 있도록 안내
오류 응답이 명확하면 화면은 실패를 막연하게 알리는 데서 끝나지 않고 사용자가 다음 행동을 선택하도록 도울 수 있습니다.
목업 데이터가 잘 보인다고 실제 연동까지 끝난 것은 아닙니다
목업 데이터는 화면 개발을 빠르게 시작하게 해주는 유용한 도구입니다. 하지만 목업의 목적은 실제 API를 대신하는 것이 아니라, 합의한 API가 완성되기 전에 동일한 구조를 미리 사용하는 데 있습니다.
서로 다른 가정이 재작업을 만듭니다
프론트엔드가 다음과 같이 가정했다고 생각해보겠습니다.
주문 상태 필드는
orderStatus가격은 숫자
날짜는 화면에 바로 출력할 수 있는 형식
배송 완료일은 항상 존재
오류 메시지는
message필드로 전달
반면 백엔드가 status, 문자열 가격, ISO 날짜, nullable 배송 완료일과 중첩된 오류 객체를 구현했다면 양쪽의 기능은 각각 정상이어도 서로 연결되지 않습니다.
이 시점에 문제를 발견하면 화면의 데이터 변환 로직과 타입, 조건문, 테스트 데이터를 한꺼번에 수정해야 합니다. 일정이 촉박할수록 임시 변환 코드가 추가되고, 그 코드는 이후 유지보수를 어렵게 만듭니다.
여기에 Image 2를 삽입합니다.
합의된 명세로 병렬 작업을 가능하게 합니다
프론트엔드와 백엔드가 요청과 응답의 예시를 먼저 합의하면 실제 API가 완성되기 전에도 같은 구조로 작업할 수 있습니다.
기획과 디자인에서 화면에 필요한 정보를 정리합니다.
프론트엔드와 백엔드가 필드명, 타입과 상태를 합의합니다.
합의한 명세로 예시 응답과 목업 데이터를 만듭니다.
프론트엔드는 목업 서버를 이용해 화면과 상태를 구현합니다.
백엔드는 동일한 명세에 맞춰 실제 API를 개발합니다.
연동 단계에서는 구조를 다시 해석하지 않고 결과만 검증합니다.
이 과정에서 중요한 것은 문서의 분량이 아니라 정확성입니다. 실제 화면 하나를 기준으로 성공 응답과 대표 오류 응답을 함께 작성하는 것만으로도 많은 오해를 줄일 수 있습니다.
Image 2 바로 다음에 Image 3을 연속으로 삽입합니다.
변경 사항은 영향 범위와 함께 관리합니다
개발 중 API가 변경될 수 있습니다. 새로운 요구사항이 발견되거나 데이터베이스 구조가 달라질 수도 있습니다. 이때는 변경 자체보다 변경 사실이 늦게 공유되는 것이 더 큰 문제입니다.
필드가 추가되거나 타입이 달라진다면 다음 내용을 함께 기록하는 편이 좋습니다.
무엇이 변경되었는지
어떤 화면과 기능에 영향을 주는지
기존 응답과 호환되는지
프론트엔드 적용이 필요한 시점
배포 순서와 담당자
기존 버전을 언제까지 유지할지
API 변경을 단순한 개발자 간 대화로 남기지 않고 제품 변경으로 관리하면 일정과 QA 범위도 더 정확하게 예측할 수 있습니다.
API 준비 상태를 확인하면 개발 일정도 더 정확해집니다
API 개발이 시작됐다는 말과 프론트엔드가 연동할 준비가 됐다는 말은 다릅니다. 엔드포인트가 존재하더라도 응답 구조, 오류 규칙과 예시 데이터가 정리되지 않았다면 화면 개발은 계속 가정을 사용하게 됩니다.
연동을 시작하기 전에 다음 항목을 점검해보세요.
API의 목적과 사용하는 화면이 명확한가
요청 필드의 이름, 타입과 필수 여부가 정리됐는가
응답 필드의 타입과 nullable 규칙이 정리됐는가
정상·빈 결과·오류 응답 예시가 준비됐는가
상태 코드와 서비스 오류 코드가 구분돼 있는가
인증과 권한에 따른 응답 차이가 정의됐는가
목록의 페이지네이션, 검색, 필터와 정렬 기준이 있는가
실제 화면을 테스트할 수 있는 예시 데이터가 있는가
변경 책임자와 버전 관리 방식이 정해졌는가
모든 항목을 거대한 문서로 만들 필요는 없습니다. 핵심 화면부터 요청과 응답, 상태와 오류를 구체적으로 합의하면 됩니다. 작은 기준 하나가 프론트엔드와 백엔드의 반복 질문을 줄이고, QA에서 발견되는 구조적인 오류도 예방합니다.
FOUR PERSPECTIVES STUDIO는 화면 기획과 UX/UI 디자인에 그치지 않고 실제 개발 과정에서 필요한 데이터 구조와 상태, 예외 처리까지 함께 설계합니다. 아이디어를 구현 가능한 제품으로 정리하거나 이미 진행 중인 프로젝트의 연동 구조를 점검해야 한다면 프로젝트의 현재 단계부터 함께 살펴보겠습니다.
Latest Blogs
DEVELOPMENT
화면 개발 전에 API 명세를 먼저 맞춰야 하는 이유
화면 개발 전에 API 명세를 먼저 맞춰야 하는 이유
API 명세는 백엔드만을 위한 기술 문서가 아닙니다. 화면에 필요한 데이터와 상태, 오류 처리 방식을 개발 전에 합의하면 프론트엔드와 백엔드가 같은 기준으로 작업할 수 있고 불필요한 재작업도 크게 줄일 수 있습니다.
API 명세는 백엔드만을 위한 기술 문서가 아닙니다. 화면에 필요한 데이터와 상태, 오류 처리 방식을 개발 전에 합의하면 프론트엔드와 백엔드가 같은 기준으로 작업할 수 있고 불필요한 재작업도 크게 줄일 수 있습니다.
API 명세는 화면과 데이터를 연결하는 약속입니다
프론트엔드 개발은 API가 완성되기 전에도 시작할 수 있습니다. 디자이너가 만든 화면을 기준으로 임시 데이터를 넣고, 버튼을 연결하고, 로딩 화면까지 구현할 수 있습니다. 문제는 이 임시 데이터에 개발자의 예상이 자연스럽게 섞인다는 점입니다.
화면에서는 주문 상태를 orderStatus로 가정했는데 실제 API는 status를 반환할 수 있습니다. 가격을 숫자로 예상했지만 통화 기호가 포함된 문자열로 전달되거나, 항상 존재할 것으로 생각한 배송 완료일이 null로 돌아올 수도 있습니다.
각각은 작은 차이처럼 보입니다. 하지만 실제 연동 단계에서 이런 차이가 여러 화면에 쌓이면 프론트엔드는 이미 완성한 컴포넌트를 다시 수정해야 하고, 백엔드는 화면의 요구에 맞춰 응답 구조를 재검토해야 합니다. QA 과정에서는 데이터 문제인지 화면 문제인지 확인하는 시간까지 필요해집니다.
API 명세는 이러한 예상의 차이를 개발 전에 발견하는 기준입니다. 여기에는 단순히 주소와 필드 이름만 적는 것이 아니라 다음 내용이 포함되어야 합니다.
어떤 화면과 기능에서 사용하는 API인지
요청할 때 필요한 값과 각 값의 형식
성공했을 때 반환되는 데이터 구조
필수 값과 선택 값,
null이 가능한 값로딩·빈 결과·오류 상태의 처리 기준
인증과 사용자 권한에 따른 차이
목록의 페이지네이션과 정렬 방식
좋은 API 명세를 만들면 기획 문서, UI 디자인, 프론트엔드 코드와 백엔드 로직이 하나의 기준으로 연결됩니다.
정상적인 데이터뿐 아니라 화면의 모든 상태를 함께 정의합니다
화면을 설계할 때는 데이터가 정상적으로 도착한 순간을 중심으로 생각하기 쉽습니다. 하지만 사용자가 실제로 만나는 화면에는 로딩, 빈 결과, 접근 제한, 네트워크 오류처럼 훨씬 다양한 상태가 존재합니다.
필드명과 데이터 타입을 먼저 맞춥니다
주문 상세 화면에 주문 번호, 결제 금액, 배송 상태와 배송 완료일이 필요하다고 가정해보겠습니다. API 명세에는 각 값이 단순히 “있다”는 사실보다 구체적인 규칙이 필요합니다.
orderId: 문자열인지 숫자인지totalPrice: 원 단위 정수인지 소수점이 포함된 값인지status: 사용할 수 있는 상태가 무엇인지deliveredAt: 아직 배송되지 않았다면null이 되는지items: 상품이 없을 때 빈 배열인지 필드 자체가 생략되는지
데이터 타입과 nullable 규칙이 빠져 있으면 프론트엔드는 임의의 방어 코드를 추가하게 됩니다. 사람마다 다른 방식으로 예외를 처리하면 같은 서비스 안에서도 화면마다 결과가 달라질 수 있습니다.
상태값은 화면 표현과 연결합니다
status: "processing"이라는 값이 단순히 API에 존재하는 것으로 끝나서는 안 됩니다. 화면에서 어떤 문구와 색상으로 보여줄지, 사용자가 주문을 취소할 수 있는지, 다음 단계는 무엇인지까지 연결해야 합니다.
예를 들어 주문 상태를 다음과 같이 합의할 수 있습니다.
pending: 결제 확인 중, 취소 가능paid: 결제 완료, 배송 준비 중shipping: 배송 중, 배송 조회 가능delivered: 배송 완료, 구매 확정 가능cancelled: 취소 완료, 재주문 가능
이렇게 상태값과 사용자 행동을 함께 정의하면 기획자, 디자이너와 개발자가 같은 의미로 상태를 이해할 수 있습니다.
오류 응답도 하나의 화면 상태입니다
오류가 발생했을 때 단순히 “오류가 발생했습니다”라고 표시하는 것으로 충분하지 않은 경우가 많습니다.
주문이 존재하지 않는 경우, 로그인이 만료된 경우, 해당 주문을 볼 권한이 없는 경우는 사용자가 취해야 할 행동이 각각 다릅니다. 따라서 상태 코드와 오류 코드, 사용자에게 보여줄 메시지의 역할을 나누어야 합니다.
401: 다시 로그인하도록 안내403: 접근 권한이 없음을 설명404: 주문을 찾을 수 없으며 목록으로 이동500: 잠시 후 다시 시도할 수 있도록 안내
오류 응답이 명확하면 화면은 실패를 막연하게 알리는 데서 끝나지 않고 사용자가 다음 행동을 선택하도록 도울 수 있습니다.
목업 데이터가 잘 보인다고 실제 연동까지 끝난 것은 아닙니다
목업 데이터는 화면 개발을 빠르게 시작하게 해주는 유용한 도구입니다. 하지만 목업의 목적은 실제 API를 대신하는 것이 아니라, 합의한 API가 완성되기 전에 동일한 구조를 미리 사용하는 데 있습니다.
서로 다른 가정이 재작업을 만듭니다
프론트엔드가 다음과 같이 가정했다고 생각해보겠습니다.
주문 상태 필드는
orderStatus가격은 숫자
날짜는 화면에 바로 출력할 수 있는 형식
배송 완료일은 항상 존재
오류 메시지는
message필드로 전달
반면 백엔드가 status, 문자열 가격, ISO 날짜, nullable 배송 완료일과 중첩된 오류 객체를 구현했다면 양쪽의 기능은 각각 정상이어도 서로 연결되지 않습니다.
이 시점에 문제를 발견하면 화면의 데이터 변환 로직과 타입, 조건문, 테스트 데이터를 한꺼번에 수정해야 합니다. 일정이 촉박할수록 임시 변환 코드가 추가되고, 그 코드는 이후 유지보수를 어렵게 만듭니다.
여기에 Image 2를 삽입합니다.
합의된 명세로 병렬 작업을 가능하게 합니다
프론트엔드와 백엔드가 요청과 응답의 예시를 먼저 합의하면 실제 API가 완성되기 전에도 같은 구조로 작업할 수 있습니다.
기획과 디자인에서 화면에 필요한 정보를 정리합니다.
프론트엔드와 백엔드가 필드명, 타입과 상태를 합의합니다.
합의한 명세로 예시 응답과 목업 데이터를 만듭니다.
프론트엔드는 목업 서버를 이용해 화면과 상태를 구현합니다.
백엔드는 동일한 명세에 맞춰 실제 API를 개발합니다.
연동 단계에서는 구조를 다시 해석하지 않고 결과만 검증합니다.
이 과정에서 중요한 것은 문서의 분량이 아니라 정확성입니다. 실제 화면 하나를 기준으로 성공 응답과 대표 오류 응답을 함께 작성하는 것만으로도 많은 오해를 줄일 수 있습니다.
Image 2 바로 다음에 Image 3을 연속으로 삽입합니다.
변경 사항은 영향 범위와 함께 관리합니다
개발 중 API가 변경될 수 있습니다. 새로운 요구사항이 발견되거나 데이터베이스 구조가 달라질 수도 있습니다. 이때는 변경 자체보다 변경 사실이 늦게 공유되는 것이 더 큰 문제입니다.
필드가 추가되거나 타입이 달라진다면 다음 내용을 함께 기록하는 편이 좋습니다.
무엇이 변경되었는지
어떤 화면과 기능에 영향을 주는지
기존 응답과 호환되는지
프론트엔드 적용이 필요한 시점
배포 순서와 담당자
기존 버전을 언제까지 유지할지
API 변경을 단순한 개발자 간 대화로 남기지 않고 제품 변경으로 관리하면 일정과 QA 범위도 더 정확하게 예측할 수 있습니다.
API 준비 상태를 확인하면 개발 일정도 더 정확해집니다
API 개발이 시작됐다는 말과 프론트엔드가 연동할 준비가 됐다는 말은 다릅니다. 엔드포인트가 존재하더라도 응답 구조, 오류 규칙과 예시 데이터가 정리되지 않았다면 화면 개발은 계속 가정을 사용하게 됩니다.
연동을 시작하기 전에 다음 항목을 점검해보세요.
API의 목적과 사용하는 화면이 명확한가
요청 필드의 이름, 타입과 필수 여부가 정리됐는가
응답 필드의 타입과 nullable 규칙이 정리됐는가
정상·빈 결과·오류 응답 예시가 준비됐는가
상태 코드와 서비스 오류 코드가 구분돼 있는가
인증과 권한에 따른 응답 차이가 정의됐는가
목록의 페이지네이션, 검색, 필터와 정렬 기준이 있는가
실제 화면을 테스트할 수 있는 예시 데이터가 있는가
변경 책임자와 버전 관리 방식이 정해졌는가
모든 항목을 거대한 문서로 만들 필요는 없습니다. 핵심 화면부터 요청과 응답, 상태와 오류를 구체적으로 합의하면 됩니다. 작은 기준 하나가 프론트엔드와 백엔드의 반복 질문을 줄이고, QA에서 발견되는 구조적인 오류도 예방합니다.
FOUR PERSPECTIVES STUDIO는 화면 기획과 UX/UI 디자인에 그치지 않고 실제 개발 과정에서 필요한 데이터 구조와 상태, 예외 처리까지 함께 설계합니다. 아이디어를 구현 가능한 제품으로 정리하거나 이미 진행 중인 프로젝트의 연동 구조를 점검해야 한다면 프로젝트의 현재 단계부터 함께 살펴보겠습니다.
Latest Blogs
DEVELOPMENT
화면 개발 전에 API 명세를 먼저 맞춰야 하는 이유
화면 개발 전에 API 명세를 먼저 맞춰야 하는 이유
API 명세는 백엔드만을 위한 기술 문서가 아닙니다. 화면에 필요한 데이터와 상태, 오류 처리 방식을 개발 전에 합의하면 프론트엔드와 백엔드가 같은 기준으로 작업할 수 있고 불필요한 재작업도 크게 줄일 수 있습니다.
API 명세는 백엔드만을 위한 기술 문서가 아닙니다. 화면에 필요한 데이터와 상태, 오류 처리 방식을 개발 전에 합의하면 프론트엔드와 백엔드가 같은 기준으로 작업할 수 있고 불필요한 재작업도 크게 줄일 수 있습니다.
API 명세는 화면과 데이터를 연결하는 약속입니다
프론트엔드 개발은 API가 완성되기 전에도 시작할 수 있습니다. 디자이너가 만든 화면을 기준으로 임시 데이터를 넣고, 버튼을 연결하고, 로딩 화면까지 구현할 수 있습니다. 문제는 이 임시 데이터에 개발자의 예상이 자연스럽게 섞인다는 점입니다.
화면에서는 주문 상태를 orderStatus로 가정했는데 실제 API는 status를 반환할 수 있습니다. 가격을 숫자로 예상했지만 통화 기호가 포함된 문자열로 전달되거나, 항상 존재할 것으로 생각한 배송 완료일이 null로 돌아올 수도 있습니다.
각각은 작은 차이처럼 보입니다. 하지만 실제 연동 단계에서 이런 차이가 여러 화면에 쌓이면 프론트엔드는 이미 완성한 컴포넌트를 다시 수정해야 하고, 백엔드는 화면의 요구에 맞춰 응답 구조를 재검토해야 합니다. QA 과정에서는 데이터 문제인지 화면 문제인지 확인하는 시간까지 필요해집니다.
API 명세는 이러한 예상의 차이를 개발 전에 발견하는 기준입니다. 여기에는 단순히 주소와 필드 이름만 적는 것이 아니라 다음 내용이 포함되어야 합니다.
어떤 화면과 기능에서 사용하는 API인지
요청할 때 필요한 값과 각 값의 형식
성공했을 때 반환되는 데이터 구조
필수 값과 선택 값,
null이 가능한 값로딩·빈 결과·오류 상태의 처리 기준
인증과 사용자 권한에 따른 차이
목록의 페이지네이션과 정렬 방식
좋은 API 명세를 만들면 기획 문서, UI 디자인, 프론트엔드 코드와 백엔드 로직이 하나의 기준으로 연결됩니다.
정상적인 데이터뿐 아니라 화면의 모든 상태를 함께 정의합니다
화면을 설계할 때는 데이터가 정상적으로 도착한 순간을 중심으로 생각하기 쉽습니다. 하지만 사용자가 실제로 만나는 화면에는 로딩, 빈 결과, 접근 제한, 네트워크 오류처럼 훨씬 다양한 상태가 존재합니다.
필드명과 데이터 타입을 먼저 맞춥니다
주문 상세 화면에 주문 번호, 결제 금액, 배송 상태와 배송 완료일이 필요하다고 가정해보겠습니다. API 명세에는 각 값이 단순히 “있다”는 사실보다 구체적인 규칙이 필요합니다.
orderId: 문자열인지 숫자인지totalPrice: 원 단위 정수인지 소수점이 포함된 값인지status: 사용할 수 있는 상태가 무엇인지deliveredAt: 아직 배송되지 않았다면null이 되는지items: 상품이 없을 때 빈 배열인지 필드 자체가 생략되는지
데이터 타입과 nullable 규칙이 빠져 있으면 프론트엔드는 임의의 방어 코드를 추가하게 됩니다. 사람마다 다른 방식으로 예외를 처리하면 같은 서비스 안에서도 화면마다 결과가 달라질 수 있습니다.
상태값은 화면 표현과 연결합니다
status: "processing"이라는 값이 단순히 API에 존재하는 것으로 끝나서는 안 됩니다. 화면에서 어떤 문구와 색상으로 보여줄지, 사용자가 주문을 취소할 수 있는지, 다음 단계는 무엇인지까지 연결해야 합니다.
예를 들어 주문 상태를 다음과 같이 합의할 수 있습니다.
pending: 결제 확인 중, 취소 가능paid: 결제 완료, 배송 준비 중shipping: 배송 중, 배송 조회 가능delivered: 배송 완료, 구매 확정 가능cancelled: 취소 완료, 재주문 가능
이렇게 상태값과 사용자 행동을 함께 정의하면 기획자, 디자이너와 개발자가 같은 의미로 상태를 이해할 수 있습니다.
오류 응답도 하나의 화면 상태입니다
오류가 발생했을 때 단순히 “오류가 발생했습니다”라고 표시하는 것으로 충분하지 않은 경우가 많습니다.
주문이 존재하지 않는 경우, 로그인이 만료된 경우, 해당 주문을 볼 권한이 없는 경우는 사용자가 취해야 할 행동이 각각 다릅니다. 따라서 상태 코드와 오류 코드, 사용자에게 보여줄 메시지의 역할을 나누어야 합니다.
401: 다시 로그인하도록 안내403: 접근 권한이 없음을 설명404: 주문을 찾을 수 없으며 목록으로 이동500: 잠시 후 다시 시도할 수 있도록 안내
오류 응답이 명확하면 화면은 실패를 막연하게 알리는 데서 끝나지 않고 사용자가 다음 행동을 선택하도록 도울 수 있습니다.
목업 데이터가 잘 보인다고 실제 연동까지 끝난 것은 아닙니다
목업 데이터는 화면 개발을 빠르게 시작하게 해주는 유용한 도구입니다. 하지만 목업의 목적은 실제 API를 대신하는 것이 아니라, 합의한 API가 완성되기 전에 동일한 구조를 미리 사용하는 데 있습니다.
서로 다른 가정이 재작업을 만듭니다
프론트엔드가 다음과 같이 가정했다고 생각해보겠습니다.
주문 상태 필드는
orderStatus가격은 숫자
날짜는 화면에 바로 출력할 수 있는 형식
배송 완료일은 항상 존재
오류 메시지는
message필드로 전달
반면 백엔드가 status, 문자열 가격, ISO 날짜, nullable 배송 완료일과 중첩된 오류 객체를 구현했다면 양쪽의 기능은 각각 정상이어도 서로 연결되지 않습니다.
이 시점에 문제를 발견하면 화면의 데이터 변환 로직과 타입, 조건문, 테스트 데이터를 한꺼번에 수정해야 합니다. 일정이 촉박할수록 임시 변환 코드가 추가되고, 그 코드는 이후 유지보수를 어렵게 만듭니다.
여기에 Image 2를 삽입합니다.
합의된 명세로 병렬 작업을 가능하게 합니다
프론트엔드와 백엔드가 요청과 응답의 예시를 먼저 합의하면 실제 API가 완성되기 전에도 같은 구조로 작업할 수 있습니다.
기획과 디자인에서 화면에 필요한 정보를 정리합니다.
프론트엔드와 백엔드가 필드명, 타입과 상태를 합의합니다.
합의한 명세로 예시 응답과 목업 데이터를 만듭니다.
프론트엔드는 목업 서버를 이용해 화면과 상태를 구현합니다.
백엔드는 동일한 명세에 맞춰 실제 API를 개발합니다.
연동 단계에서는 구조를 다시 해석하지 않고 결과만 검증합니다.
이 과정에서 중요한 것은 문서의 분량이 아니라 정확성입니다. 실제 화면 하나를 기준으로 성공 응답과 대표 오류 응답을 함께 작성하는 것만으로도 많은 오해를 줄일 수 있습니다.
Image 2 바로 다음에 Image 3을 연속으로 삽입합니다.
변경 사항은 영향 범위와 함께 관리합니다
개발 중 API가 변경될 수 있습니다. 새로운 요구사항이 발견되거나 데이터베이스 구조가 달라질 수도 있습니다. 이때는 변경 자체보다 변경 사실이 늦게 공유되는 것이 더 큰 문제입니다.
필드가 추가되거나 타입이 달라진다면 다음 내용을 함께 기록하는 편이 좋습니다.
무엇이 변경되었는지
어떤 화면과 기능에 영향을 주는지
기존 응답과 호환되는지
프론트엔드 적용이 필요한 시점
배포 순서와 담당자
기존 버전을 언제까지 유지할지
API 변경을 단순한 개발자 간 대화로 남기지 않고 제품 변경으로 관리하면 일정과 QA 범위도 더 정확하게 예측할 수 있습니다.
API 준비 상태를 확인하면 개발 일정도 더 정확해집니다
API 개발이 시작됐다는 말과 프론트엔드가 연동할 준비가 됐다는 말은 다릅니다. 엔드포인트가 존재하더라도 응답 구조, 오류 규칙과 예시 데이터가 정리되지 않았다면 화면 개발은 계속 가정을 사용하게 됩니다.
연동을 시작하기 전에 다음 항목을 점검해보세요.
API의 목적과 사용하는 화면이 명확한가
요청 필드의 이름, 타입과 필수 여부가 정리됐는가
응답 필드의 타입과 nullable 규칙이 정리됐는가
정상·빈 결과·오류 응답 예시가 준비됐는가
상태 코드와 서비스 오류 코드가 구분돼 있는가
인증과 권한에 따른 응답 차이가 정의됐는가
목록의 페이지네이션, 검색, 필터와 정렬 기준이 있는가
실제 화면을 테스트할 수 있는 예시 데이터가 있는가
변경 책임자와 버전 관리 방식이 정해졌는가
모든 항목을 거대한 문서로 만들 필요는 없습니다. 핵심 화면부터 요청과 응답, 상태와 오류를 구체적으로 합의하면 됩니다. 작은 기준 하나가 프론트엔드와 백엔드의 반복 질문을 줄이고, QA에서 발견되는 구조적인 오류도 예방합니다.
FOUR PERSPECTIVES STUDIO는 화면 기획과 UX/UI 디자인에 그치지 않고 실제 개발 과정에서 필요한 데이터 구조와 상태, 예외 처리까지 함께 설계합니다. 아이디어를 구현 가능한 제품으로 정리하거나 이미 진행 중인 프로젝트의 연동 구조를 점검해야 한다면 프로젝트의 현재 단계부터 함께 살펴보겠습니다.