Today I Learned
RESTful한 API 설계란 무엇인가
오늘 아웃소싱 프로젝트의 프론트엔드 코드와 요청사항을 전달받고, 팀원들과 함께 API 명세와 ERD를 설계하는 시간을 가졌다.
이 과정에서 단순한 RESTful 규칙을 넘어, 실제 설계 시 어떤 기준으로 URI를 나누고, 관계를 표현할 것인지에 대해 깊이 고민하게 되었다.
RESTful 설계
1. 자원(Resource)의 경계 정의
단순히 명사로 URI를 구성하는 것보다 중요한 건 자원의 경계를 명확히 정의하는 것이다.
`/users/{id}/posts`는 사용자와 게시글 간의 관계를 표현하지만,
이 관계가 단방향인지, 독립적인지, 종속적인지에 따라 URI 구조가 달라질 수 있다.
자원 간의 관계를 표현할 때는 “소유” vs “참조”의 개념을 구분해야 한다.
2. 행위가 아닌 상태를 표현
REST는 행위 중심이 아니라 자원의 상태 변화를 표현해야 한다.
`/posts/{id}/publish`는 RESTful하지 않다. 대신 `PATCH /posts/{id}`로 `status: published`를 전달하는 방식이 더 적절하다.
API는 “무엇을 한다”가 아니라 “무엇이 바뀌는가”를 표현해야 한다.
3. 컬렉션과 단일 자원의 구분
`/comments`는 댓글 목록을 의미하고, `/comments/{id}`는 단일 댓글을 의미한다.
대댓글을 `/comments/{id}/replies`로 표현할지, `/comments?parentId={id}`로 표현할지는 조회 방식과 트리 구조에 따라 판단해야 한다.
URI는 구조를 표현하고, 쿼리 파라미터는 필터링을 표현한다.
4. 비정형 행위의 처리
좋아요, 팔로우, 신고 등은 자원으로 보기 애매한 경우가 많다.
이럴 땐 POST `/posts/{id}/likes`처럼 행위를 자원처럼 표현하는 방식이 일반적이다.
단, 너무 많은 행위가 생기면 RESTful 구조가 오히려 복잡해질 수 있음을 주의해야한다.
마치며
오늘은 아웃소싱 프로젝트의 프론트엔드 요청사항을 바탕으로 팀원들과 함께 API 명세와 ERD를 설계했다. 단순히 URI를 나열하는 작업이 아니라, 비즈니스 흐름을 어떻게 기술로 표현할 것인가에 대한 고민이 깊어졌다. 처음엔 “RESTful하게 설계하자”는 말이 단순한 규칙처럼 들렸지만, 실제로 하나하나 URI를 정의하고 자원의 경계를 나누다 보니 그건 규칙이 아니라 비즈니스 로직을 설명하는 문장이어야 했다. 예를 들어, 어떤 자원이 누구에게 속해 있는지, 어떤 행위가 상태를 어떻게 바꾸는지, 그 모든 걸 URI와 메서드로 표현해야 했다. 그리고 프론트엔드가 어떤 흐름으로 데이터를 소비할지, 어떤 순서로 호출할지까지 고려하다 보니 API 설계는 결국 서로 다른 팀 간의 소통을 위한 인터페이스라는 걸 다시금 깨달았다.