✴️ HTTP API 설계 예시
⭐️ POST 기반 등록
예를 들어 회원 관리 시스템을 운영한다고 가정하고 API를 설계해보자.
- 회원 목록
/members➡️ GET - 회원 등록
/members➡️ POST - 회원 조회
/members/{id}➡️ GET - 회원 수정
/members/{id}➡️ PATCH, PUT, POST - 회원 삭제
/members/{id}➡️ DELETE
먼저 전체 회원 목록을 조회하기 위해서는 GET을 사용해야 한다.
🤔 하지만 회원이 100만 명이라면? 회원끼리 구분할 수 있는 검색어를 쿼리 파라미터로 넣어주면 된다. 또한 회원 목록을 조회할 때 정렬 기능을 사용한다면, 정렬 조건도 쿼리 파라미터로 넣어주면 된다.
회원 등록은 POST를 사용한다. 등록하고자 하는 회원의 데이터는 POST 요청 메세지 내 메세지 바디에 넣어 서버에 보낼 수 있다.
개인 회원 조회는 GET을 사용한다. members 라는 컬렉션 아래 각각의 회원을 id 로 구분한다.
개인 회원 수정은 PATCH, PUT, POST를 사용할 수 있다.
이중에서 회원 데이터 수정에 가장 적합한 메서드는 PATCH이다. 데이터를 수정할 때는 보통 기존 데이터에서 필요한 부분만 수정 요청을 하는 식으로 진행되는데, PUT은 완전히 기존 리소스를 대체하는 방식을 가지고 있기 때문에 PATCH가 가장 적합하다. 만약 리소스가 완전히 대체되더라도 상관 없는 경우, PUT을 사용해도 무관하다.
또한 이것도 애매하고, 저것도 애매한 경우라면 POST를 사용하는 것이 안전할 수 있다.
개인 회원 삭제는 DELETE를 사용한다. 조회, 수정과 마찬가지로 URI 내에 id 가 포함된다.
POST로 데이터를 등록할 때는 보통 서버에서 리소스 URI를 결정하고 생성한다. 고로 클라이언트는 등록될 URI의 리소스를 모른다.
이때 컬렉션(Collection) 이라는 개념이 등장한다. 컬렉션은 서버가 관리하는 리소스 디렉토리이며, 컬렉션 하위에 들어갈 리소스의 URI도 서버가 생성하고 관리한다. 회원 관리 시스템에서는 /members 가 컬렉션이 된다.
HTTP API를 설계하는 대부분의 경우에서 이 방식을 사용한다❗️
⭐️ PUT 기반 등록
예를 들어 파일 관리 시스템을 운영한다고 가정하고 API를 설계해보자.
- 파일 목록
/files➡️ GET - 파일 조회
/files/{filename}➡️ GET - 파일 등록
/files/{filename}➡️ PUT - 파일 삭제
/files/{filename}➡️ DELETE - 파일 대량 등록
/files➡️ POST
전체 파일 목록을 조회할 때나 개별 파일을 조회하기 위해서는 GET을 사용해야 한다. 개별 파일 조회시에는 클라이언트만 알고 있는 파일명을 URI에 포함시켜서 전달한다.
파일 등록은 PUT을 사용한다. 이는 현재 업로드하는 파일의 파일명과 동일한 파일명의 파일이 서버에 존재하지 않을 경우 새로 생성하며, 존재할 경우 이를 완전히 대체하도록 한다.
파일 삭제는 DELETE를 사용한다. 조회, 등록과 마찬가지로 URI에 파일명이 포함된다.
파일 대량 등록은 POST를 사용한다고 지정하고, POST가 어떤 기능을 할지는 서버와 정하면 된다.
PUT 기반 등록이 POST 기반 등록과 가장 크게 다른 점은 PUT을 사용하기 때문에 클라이언트가 리소스 URI를 알고 있어야 한다는 점이다. 따라서 클라이언트가 등록될 리소스의 URL을 직접 관리하게 된다.
이러한 관리 방식을 스토어(Store) 라고 한다. 스토어는 클라이언트가 관리하는 리소스 저장소로, 리소스의 URI를 관리한다. 파일 관리 시스템에서는 /files 가 스토어가 된다.
Reference
