협업 도구(푸딩/두레이 계열)의 REST API를 설계·운영해 온 개발자가, 다시 만든다면 어떻게 바꿀지를 사례 중심으로 되짚는 회고다. 『REST API Design Rulebook』의 표현(Representation) 설계를 기준으로 조직·프로젝트·업무·파일·태그의 리소스 계층을 잡은 과정과, 그 위에서 실제로 후회했던 결정들을 하나씩 꺼낸다.
핵심 포인트- POST 생성 응답을 아이디만 반환하는 대신 **201 Created + Content-Location**으로 표준을 따랐어야 했다는 반성
- 업무 목록마다 **프로젝트 전체를 중복 임베딩**해 표현이 비대해진 문제와, 프로젝트 아이디만 남기고 참조 필드로 분리한 개선
- 임시저장(드래프트)·파일 업로드를 별도 리소스로 두는 방식, **HTTP 캐시(ETag)**·계산된 속성(삭제 권한 등) 캐싱의 어려움
- 프로젝트 간 업무 이동 시 URL이 바뀌어 사용자가 업무를 잃는 함정과, **PATCH(RFC 5789)**·읽음 처리를 표준대로 살피지 못한 후회
왜 읽나REST 리소스 모델링에서 실제 운영이 쌓인 뒤에야 드러나는 함정과 트레이드오프를 남의 실패로 미리 배울 수 있다.