Skip to content

공부 목표: API 설계 원칙 ​

상태: 시작 전 · 작성일: 2026-09-09 · 목표 수준: Java·Spring 미들급 개발자의 독립적인 구현·검증·문제 해결

학습 목적 ​

리소스와 API 계약을 설계하고, 이미 사용 중인 클라이언트를 깨지 않으면서 API를 바꾸는 방법을 설명한다. 5번 주제가 "요청이 실패하지 않게 처리하는 법"이라면, 이 주제는 "다른 팀·클라이언트가 안전하게 쓸 수 있는 API를 만드는 법"이다.

학습 우선순위: Spring 요청 처리(2번)와 HTTP·외부 API(5번) 학습 후 진행한다. 사내 API를 새로 설계하거나 기존 API를 변경하는 업무가 있으면 우선순위를 높인다.

학습 환경 ​

  • Java / Spring Boot 버전: 미정
  • DB / 데이터 접근 기술: 미정
  • 실습 코드 위치: 미정

현재 프로젝트의 기술과 버전을 적은 뒤 시작한다. 확인하지 않은 동작은 가정으로 표시하고 실습으로 검증한다.

핵심 개념별 목표 ​

  • [ ] 리소스 모델링: URL을 동사가 아니라 자원으로 표현하고, 컬렉션과 단일 자원, 하위 자원의 계층 구조를 설계한다.
  • [ ] HTTP 메서드와 상태 코드의 의미: GET·POST·PUT·PATCH·DELETE를 각각 언제 쓰는지, 2xx·4xx·5xx를 어떤 기준으로 구분하는지 정한다. 오류 응답의 스키마를 API 전체에서 통일한다.
  • [ ] 요청·응답 계약과 검증: 입력 검증을 어느 계층에서 할지, 응답 필드의 null 처리 원칙, 외부에 노출하는 DTO와 내부 도메인 모델을 분리하는 이유를 설명한다.
  • [ ] 버저닝 전략: URL·헤더·미디어타입 버저닝 방식을 비교하고 언제 새 버전이 필요한지 판단한다.
  • [ ] 하위 호환을 깨지 않는 변경: 필드 추가·제거·타입 변경이 기존 클라이언트에 미치는 영향을 각각 구분한다.
  • [ ] 페이징·정렬·필터링 설계: 오프셋 기반과 커서 기반 페이징의 차이, 데이터가 중간에 추가·삭제될 때의 동작 차이를 설명한다.
  • [ ] API 문서화: OpenAPI(Swagger) 스펙과 실제 동작이 어긋나지 않게 유지하는 방법을 이해한다.

실습 과제 ​

  1. 기존 API 하나를 골라 리소스 구조·메서드·상태 코드·오류 응답 스키마 관점에서 리뷰하고 문제점을 목록화한다.
  2. 응답에 필드를 추가하는 변경과 제거하는 변경을 각각 실습하고, 기존 클라이언트 코드가 깨지는 경우와 깨지지 않는 경우를 구분한다.
  3. 목록 조회 API를 오프셋 방식과 커서 방식으로 각각 구현하고, 조회 중간에 데이터가 추가·삭제되는 상황에서 결과가 어떻게 달라지는지 비교한다.
  4. OpenAPI 스펙을 작성하고 실제 응답과 대조해 불일치를 찾아 수정한다.

스스로 설명할 질문 ​

  • PUT과 PATCH의 차이는 무엇이고, 각각 언제 사용해야 하는가?
  • 이미 배포된 API 응답에서 필드 하나를 제거하면 어떤 클라이언트가 영향을 받는가?
  • 커서 기반 페이지네이션이 꼭 필요한 상황은 언제인가?

완료 기준 ​

  • [ ] 자원 모델링과 상태 코드 선택의 근거를 실제 API 예시로 설명한다.
  • [ ] 하위 호환을 깨는 변경과 깨지 않는 변경을 구분하고 각각 사례를 든다.
  • [ ] 버저닝 전략을 하나 선택하고 트레이드오프를 설명한다.
  • [ ] 실패 또는 경계 조건을 최소 하나 직접 재현하고 결과를 기록한다.
  • [ ] 선택한 방법과 대안의 비용을 비교하고 코드·테스트·로그 등 검증 근거를 연결한다.

개념 체크는 자신의 말로 설명하고 예제에서 확인했을 때 표시한다. 문서나 강의를 읽은 것만으로 완료 처리하지 않는다.

학습 기록과 확장 ​

  • 학습 노트: 아직 없음
  • 실습 결과: 아직 없음
  • 남은 질문: 아직 없음

GraphQL, gRPC, API 게이트웨이는 REST 기반 설계에 익숙해진 뒤 필요에 따라 확장한다.

세부 주제가 커지면 이 폴더 안에 해당 주제의 폴더와 공부 목표.md를 만들고 여기에 상대 링크를 추가한다. 실제 학습 기록은 목표 문서와 별도 파일로 남긴다.

참고 자료 ​

공식 문서는 설치된 버전에 맞춰 확인한다. DB 예시는 사용 DB가 다르면 해당 제품의 문서와 실험으로 대체한다.

전체 공부 목표로 돌아가기