Code First
- 백엔드 구현 완료 후 문서 작성
- 문서가 늦게 따라가거나 누락되기 쉬움
- 구조 결정이 구현 편의에 치우치기 쉬움
이 파트에서 다루는 내용
CH 01 API란 무엇인가CH 02 왜 API 설계를 먼저 해야 하는가CH 03 REST API란 무엇인가CH 04 왜 결국 OpenAPI(Swagger)로 가는가
01
API는 코드가 아니라 약속입니다
프론트엔드와 백엔드는 같은 화면과 데이터를 두고 일하지만 서로 다른 코드베이스에서 움직입니다. 둘이 어긋나지 않으려면 이 주소로 요청하면 이런 데이터를 돌려준다는 약속이 필요합니다.
그 약속이 API입니다. API를 구현 함수처럼만 보면 응답 구조가 쉽게 바뀌고, 프론트는 화면이 깨진 뒤에야 문제를 알게 됩니다.
핵심 전제
API는 기능 목록이 아니라 협업 계약입니다. 계약은 말로 전달하면 깨지고, 문서와 스펙으로 남겨야 유지됩니다.
02
Design First는 병렬 개발을 가능하게 합니다
코드 우선 방식에서는 백엔드 구현이 끝난 뒤 문서를 따라 적는 경우가 많습니다. 이때 응답 구조는 구현 편의에 맞춰지고 프론트는 뒤늦게 맞춰야 합니다.
설계 우선 방식에서는 OpenAPI 스펙 또는 API 명세를 먼저 합의합니다. 프론트와 백엔드는 같은 약속을 보며 동시에 개발을 시작할 수 있습니다.
Design First
- 요청/응답 구조를 먼저 합의
- 프론트와 백엔드 병렬 개발 가능
- 변경 리스크를 PR과 리뷰에서 먼저 발견
03
REST는 자원과 HTTP 메서드로 약속을 표현합니다
REST는 URL에 동작을 적는 방식이 아니라 자원을 표현하는 방식입니다. URL은 상품, 사용자, 주문 같은 자원을 가리키고, 무엇을 할지는 HTTP 메서드가 표현합니다.
상태 코드도 API 계약의 일부입니다. 200, 201, 400, 401, 403, 404, 500을 정확히 쓰면 클라이언트는 본문을 열기 전에 상황을 판단할 수 있습니다.
REST 리소스 예시http
GET /products # 상품 목록 조회
GET /products/12 # 12번 상품 조회
POST /products # 상품 생성
PUT /products/12 # 12번 상품 전체 수정
PATCH /products/12 # 12번 상품 일부 수정
DELETE /products/12 # 12번 상품 삭제URL은 자원, 메서드는 행위를 표현합니다.
04
OpenAPI는 약속을 기계가 읽을 수 있게 만듭니다
문서가 코드와 따로 놀면 API 계약은 반드시 흔들립니다. 노션이나 워드에 적은 명세는 코드가 바뀌어도 자동으로 따라오지 않습니다.
OpenAPI는 YAML 또는 JSON으로 작성하는 표준 API 스펙입니다. 이 스펙에서 Swagger UI, 클라이언트 코드, 테스트 초안을 만들 수 있어 문서가 하나의 기준점이 됩니다.
Swagger의 위치
Swagger는 OpenAPI 스펙을 사람이 보기 좋게 보여주고 테스트하게 해주는 생태계입니다. 핵심은 UI가 아니라 스펙을 기준으로 협업하는 구조입니다.
체크