REST API 설계의 핵심: 리소스와 컬렉션 이해
카테고리
프로그래밍/소프트웨어 개발
서브카테고리
웹 개발
대상자
- *웹 API 개발자 및 설계자** (중간 수준)
- RESTful API 설계 원칙과 HTTP 메서드 사용법을 이해하고자 하는 개발자
- 리소스 정의 및 컬렉션 구조를 기반으로 한 API 설계를 수행해야 하는 팀
핵심 요약
- 리소스(Resource)는 URI로 식별되는 개념적 엔티티로, JSON, XML 등 다양한 포맷으로 표현 가능하다.
- 컬렉션(Collection)은 동일한 유형의 리소스를 그룹화한 URI(예:
/users)로, 명확한 계층 구조를 제공한다. - HTTP 메서드(GET, POST, PUT, DELETE)를 통해 리소스에 대한 CRUD 작업을 수행하며, 명사 중심의 URI 설계가 핵심 원칙이다.
섹션별 세부 요약
1. REST에서의 리소스 정의
- 리소스는 데이터베이스 테이블이 아닌, 애플리케이션 도메인에서 중요한 개념적 엔티티다.
- 예: 사용자 프로필, 제품 정보, 이미지 변환 서비스 등.
- URI의 고유성이 필수적이며,
/users/123과 같은 식별자가 사용된다. - 표현 다양성을 통해 클라이언트가
Accept헤더를 통해 JSON 또는 HTML을 요청할 수 있다.
2. 컬렉션의 역할과 구조
- 컬렉션은 여러 리소스를 그룹화한 URI(예:
/products)로, 계층적 구조를 통해 관리가 용이하다. - 컬렉션 내 리소스는
/users/123과 같은 하위 URI로 접근 가능하며, 일관된 패턴을 유지해야 한다. - 컬렉션은 API의 예측 가능성을 높이고, 개발자에게 직관적인 상호작용 경험을 제공한다.
3. REST 설계의 핵심 원칙
- 명사 중심 URI: URI는 명사(예:
/users)를 사용하고, HTTP 메서드(GET,POST)로 동작을 지정한다. - 상태 없음(Stateless): 요청은 클라이언트가 모든 정보를 포함해야 하며, 서버는 세션 정보를 저장하지 않는다.
- HTTP 메서드 활용:
GET은 조회,POST는 생성,PUT은 업데이트,DELETE는 삭제를 위한 표준 방식이다.
결론
- RESTful API 설계 시 URI의 명확성과 HTTP 메서드의 적절한 사용이 핵심이다.
- 도구(Apidog)를 활용해 버전 관리와 문서화를 간소화하고, 일관된 리소스 구조를 유지해야 한다.
- 컬렉션과 리소스의 계층적 관계를 명확히 정의함으로써 API의 확장성과 유지보수성을 향상시킬 수 있다.