🔥 RESTful API 설계 전략과 지향점

✨ 서비스 개요

CHOOZ는 사용자가 여러 장의 사진 중 "SNS에 어떤 사진을 올릴지 고민될 때" 도움을 받기 위해 만든 사진 기반 투표 SNS 서비스입니다. 사진 업로드와 투표 생성, 실시간 결과 확인, 댓글 참여, 공유 등 다양한 API를 서버에서 제공합니다.

---

✅ RESTful API 설계 전략

1. 도메인 중심의 리소스 설계

• 모든 API 엔드포인트는 도메인 개념(Post, Comment, Notification, User 등)을 중심으로 나뉘었습니다.
• /api/posts, /api/users/me, /api/notifications 등 리소스 경로 유지

2. HTTP Method의 역할 분리

• GET: 조회
• POST: 생성/액션 트리거
• PUT: 전체 수정
• PATCH:일부 수정
• DELETE: 삭제

예시: /api/users/me/device-tokens 하나의 엔드포인트에서

• POST로 등록
• DELETE로 해제

3. 리소스 계층 구조 표현

• /posts/{postId}/comments, /posts/{postId}/choices와 같이 하위 리소스를 명확하게 표현하여 의미 전달력 강화

4. Query Parameter 활용 최적화

• 페이징, 정렬, 필터 조건은 모두 Query로 처리

  • /api/posts?cursor=...&size=10
  • /api/posts/{postId}/comments?page=0&size=5

• 캐싱과 브라우저 히스토리를 위해 같은 url에서 조건만 바뀌는 조회일 경우, 쿼리파라미터 적극적 활용

5. me 표현 도입

• 사용자 ID를 알지 않고도 클라이언트에서 내 정보 처리 가능

6. 공개범위에 따른 설계 분기

• /posts/{id}: 공개 또는 내 게시물만 접근 가능
• /posts/share/{token}: 난수 기반 공유 링크 접근 전용
• 서버에서는 항상 권한 검증(토큰 또는 작성자 여부)

7. 푸시알림은 비동기 내부 트리거로 처리

• 투표, 댓글 등의 이벤트 발생 시 서버 내부에서 알림 발송
• REST API는 디바이스 등록, 알림 설정만 제공하고, 실제 발송은 로직에 내재화

8. 확장 가능한 전략 패턴 구조 도입

• /users/me/posts?type=created 등 쿼리 기반 분기는 전략 패턴으로 처리
• switch-case가 아닌 ~Strategy 인터페이스로 각 타입을 유연하게 분리 → OCP

---

🔐 보안 설계 원칙 적용 사례

✅ /users/me vs /users/{userId} 명확한 분리

• /users/me: 민감 정보 포함 가능 (이메일, 알림 설정 등)
• /users/{userId}: 프로필만 공개, 다른 유저 정보는 권한 제한 필수

🔍 이유 및 장점

비교 항목	/users/me	/users/{userId}
민감 정보 포함	✅	❌
userId 노출 필요	❌	✅
인증 기반 처리	✅	⚠️

/me는 JWT 기반 사용자 판별이 확정적이므로 실수 가능성이 거의 없음
/users/{userId}는 보안 실수로 인해 다른 사용자의 정보가 노출될 수 있음(권한체크로직 필수)
공개된 프로필 게시물 조회시에만, {userId}로 접근.

예시 문제

//내정보조회
@putMapping("/users/{userId}") 
public UserInfo getUser(@PathVariable Long userId) {
    return userRepository.findById(userId); // 권한 체크 빠짐
}

필수사항

• /me는 민감 정보 전용(내정보조회 및 수정)
• /users/{id}는 공개 정보 전용(상대프로필 조회)
• 프론트엔드는 두 경로를 명확히 구분해 사용

---

🔬 고려한 RESTful 설계

1. 자원 중심(Resource-Oriented)
   • 모든 기능은 도메인 단위 리소스로 분리됨
2. HTTP 명세 준수
   • 메서드 별 역할 구분 (GET, POST, DELETE, PUT)
3. URI의 일관성과 명확성
   • /posts/{id} vs /posts/share/{token} 구분 명확
4. 무상태성(Stateless)
   • JWT 토큰으로 인증, 요청마다 독립 처리
5. 클라이언트-서버 분리
   • 프론트는 상태만 관리, 백엔드는 명확한 API 응답 설계
6. 캐시 가능성
   • GET 요청 중심의 리스트 조회는 캐싱 가능성 고려함

---

✨ 마무리

CHOOZ의 API는 단순한 CRUD 설계가 아닌, 도메인 구조에 기반한 명확하고 RESTful한 설계 전략을 만드는 것이 목표.
유지보수성, 확장성, 사용자경험과 관련된 효율적인 API설계 필요.