생산성 높은 .NET API 설계: Part 1 - 깔끔하고 직관적인 API 설계
카테고리
프로그래밍/소프트웨어 개발
서브카테고리
웹 개발
대상자
.NET API 설계를 담당하는 개발자 및 팀.
- 중급 이상의 기술 역량을 가진 개발자에게 적합
- REST API 설계 패턴과 실무 적용 방법을 배우고자 하는 대상
핵심 요약
- CRUD 기반 API 설계는 기술 부채를 유발하고, Task-Based API 설계로 전환해야 한다.
OrderDto
처럼 입력/출력 모델을 분리하고,SetShippingInfoRequest
와ShippingInfoResponse
처럼 명확한 요청/응답 타입을 정의하라.- 구조화된 오류 응답(예:
ValidationProblemDetails
)과 Swagger 문서에 예제 포함하여 클라이언트의 예상 범위를 명확히 하라.
섹션별 세부 요약
- HTTP 메서드 오류
POST
대신PUT
또는PATCH
를 사용해야 한다.POST
는 자원 생성에,PATCH
는 부분 업데이트에 적합하다.
- CRUD 기반 설계의 한계
CancelOrder
또는MarkOrderAsPaid
와 같은 Task-Based 엔드포인트로 전환하여 도메인 로직을 명확히 하라.- CRUD 방식은 시간이 지나면 복잡한 조건 처리로 인해 유지보수가 어려워진다.
- 모델 분리 및 명확한 응답 타입
OrderDto
처럼 입력/출력을 모두 처리하는 모델은 혼란을 유발한다.SetShippingInfoRequest
와ShippingInfoResponse
처럼 분리된 모델을 사용하여 인터페이스와 내부 로직을 분리하라.
- 구조화된 오류 응답과 문서화
400 Bad Request
는 문맥 없는 응답으로,ValidationProblemDetails
와 같은 구조화된 오류 형식을 사용해야 한다.- Swagger 문서에 XML 주석과 예제를 추가하여 클라이언트가 예상하는 입력/출력을 명확히 하라.
- 응답 형식 선택
PATCH
요청 시204 No Content
를 반환하는 것이 효율적일 수 있다.- 클라이언트가 결과를 확인해야 할 경우
ShippingInfoResponse
와 같은 구체적인 응답 모델을 사용하라.
결론
- CRUD 기반 API는 기술 부채를 유발하므로, Task-Based 설계로 전환하라.
- 명확한 HTTP 메서드, 분리된 요청/응답 모델, 구조화된 오류 응답과 Swagger 문서의 예제 포함을 통해 클라이언트 경험을 향상시킬 수 있다.
204 No Content
와 같은 단순 응답이 필요할 때는 필요한 정보만 전달하고, 추가 정보가 필요할 경우 구체적인 응답 모델을 사용하라.