API 계약 설계 — 리소스·상태코드·버저닝·에러 형식 — 실습 Lab

INCIDENT RESPONSE

0 / 5 단계 완료

📚 PREREQUISITES

Theorysw-engineering/api-contract

TRACK

SW-ENGINEERING

SLA

55분

LEVEL

중급

PHASES

3단계

ENV

local

INCOMING TICKET

“백엔드 리드: "프론트팀이랑 API 때문에 매번 통합 직전에 싸워요. 필드 이름이 다르고, 에러 형식이 제각각이고, 어느 상태코드가 뭘 뜻하는지도 안 맞아요. 우리 서비스 주문 API의 계약을 먼저 문서로 확정해서, 프론트·백이 같은 걸 보고 만들게 해 주세요."”

YOUR ROLE

API 계약을 설계·합의하는 담당

안 하면 나중에

계약이 없으면 프론트와 백이 서로 다른 걸 만들었다는 사실이 통합 시점에야 드러나고, 배포 후 필드 하나 바꾸면 클라이언트가 조용히 깨진다.

📋상황 브리핑

백엔드 리드가 말합니다.

"프론트팀이랑 통합할 때마다 전쟁이에요. 주문 조회가 어떤 팀은 GET /order, 어떤 팀은 POST /getOrder로 부르고, 실패했을 때 어떤 건 500, 어떤 건 200에 body로 error를 담아 보내요. 에러 형식도 제각각이라 프론트가 매번 다르게 처리하고요. 우리 주문 API의 계약을 먼저 확정합시다. 리소스와 메서드, 상태코드, 에러 형식, 버저닝까지 규칙으로요. 그래야 프론트·백이 같은 문서를 보고 만들죠."

API 계약은 "두 팀이 대화하는 규약"이다. 이 Lab은 주문 API의 리소스·상태코드를 설계하고, 에러·페이지네이션·버저닝을 일관 규칙으로 세운 뒤, 계약을 먼저 합의해 통합 리스크와 깨지는 변경을 통제한다.

⏱ 55분📊 중급🔧 3단계#api#rest#contract#http-status

MISSION

리소스·메서드·상태코드 설계

주문을 자원으로 모델링하고, 행위를 HTTP 메서드로, 결과를 적절한 상태코드로 표현한다.

에러 응답·페이지네이션·버저닝 규칙

실패 응답을 일관된 형식으로 통일하고, 목록의 페이지네이션과 API 버저닝 규칙을 정한다.

계약 우선(contract-first) + 호환성 깨는 변경 판단

스키마를 먼저 합의해 프론트·백이 병행 개발하게 하고, 어떤 변경이 호환성을 깨는지 판단해 통제한다.

📌 선수 지식

• [이론] sw-engineering/api-contract

ℹ️ 실습 환경

환경: local

🔒

실습 실행은 Pro 플랜 전용입니다

인시던트 브리프와 학습 자료는 지금 바로 확인할 수 있습니다. 실제 실습 진행 및 터미널 사용은 Pro 플랜에서 가능합니다.

Pro로 업그레이드 →

>_ LAB TERMINAL↔ 너비 조절

NOTES