HTTP API - 컬렉션과 스토어

HTTP API를 설계할 때 컬렉션과 스토어라는 개념이 등장한다.

 

컬렉션 (Collection)

컬렉션의 예시에 대해 살펴보자.

 

ex) /members [POST] (회원 등록 API)

위 예시에서 members가 바로 컬렉션이다.

 

해당 API로 회원 등록 요청 시, 클라이언트는 회원 ID 등 리소스의 URI를 알 수 없다.

(요청 이후 응답의 Location 헤더 등으로 알 수 있다.)

즉, 컬렉션은 서버가 리소스의 URI를 생성하고 관리하는 방식이다.

그렇기에 컬렉션을 "Server-Managed Resource Directory"라고 부른다.

 

여기서 컬렉션은 /members이다.

 

스토어 (Store)

다음으로는 스토어의 예시에 대해 살펴보자.

 

ex) /files/{file-name} [PUT] (사진 등록 API)

위 예시에서 files가 바로 스토어이다.

 

해당 API로 사진 등록 요청 시, 클라이언트는 파일명 등 리소스의 URI를 이미 알고 있다.

즉, 스토어는 클라이언트가 리소스의 URI를 생성하고 관리하는 방식이다.

그렇기에 스토어를 "Client-Managed Resource Repository"라고 부른다.

 

여기서 스토어는 /files이다.

 

POST vs PUT

위의 두 URI를 살펴보면, 각각 POST와 PUT 메서드임을 알 수 있다.

분명 두 상황 모두 리소스를 생성하는 상황 같은데, 두 메서드의 본질적인 차이는 무엇일까?

POST 메서드를 통해 리소스를 생성하는 상황에서는, 클라이언트는 당연히 리소스의 URI를 알지 못한다.

회원가입 상황을 예로 들면, 클라이언트는 자신의 회원 정보가 어떤 회원 ID로 저장될지 알 수 있는 방법이 없기 때문이다.

따라서 POST 메서드의 경우, 신규 리소스를 '생성'할 때 사용할 수 있다.

(물론 POST 메서드는 신규 리소스 생성 이외에도 서버 사이드에서 다양한 처리를 수행하는 데 사용될 수 있다.)

 

PUT 메서드를 통해 리소스를 등록하는 상황에서는, 클라이언트가 리소스의 URI를 이미 알고 있었다.

사실 PUT 메서드는 리소스를 '대체'할 때 사용하기 때문이다.

여기서 말하는 '대체'란, 쉽게 말해 '생성'과 '덮어쓰기'를 모두 포함한다.

 

즉, PUT 메서드의 경우 리소스를 대체하겠다는 의도이기 때문에, 클라이언트가 리소스의 URI를 알고 있을 수 밖에 없는 것이다.

이때 클라이언트가 URI에 명시한 리소스가 서버 사이드에 존재할 경우, 리소스를 덮어쓴다.

그러나 존재하지 않을 경우, 신규 리소스를 생성하게 된다.

 

정리

마지막으로 표로 정리해 봤다.

컬렉션 (Collection)	스토어 (Store)
Server-Managed Resource Resource Directory (서버가 관리하는 리소스 디렉터리)	Client-Managed Resource Repository (클라이언트가 관리하는 리소스 저장소)
클라이언트는 리소스의 URI를 모름 (POST)	클라이언트가 리소스의 URI를 앎 (PUT)
서버가 리소스의 URI를 생성 및 관리	클라이언트가 리소스의 URI를 지정 및 관리

 

 

 

Reference

https://www.inflearn.com/course/http-%EC%9B%B9-%EB%84%A4%ED%8A%B8%EC%9B%8C%ED%81%AC/dashboard

모든 개발자를 위한 HTTP 웹 기본 지식 강의 | 김영한 - 인프런

https://restfulapi.net/resource-naming/

REST API URI Naming Conventions and Best Practices