HTTP(10) - HTTP API 설계 예시

회원 관리 시스템 - POST 기반 등록

• 회원 목록 /members GET
• 회원 등록 /members POST
• 회원 조회 /members/{id} GET
• 회원 수정 /members/{id} PUT, PATCH, POST
• 회원 삭제 /members/{id} DELETE

POST 기반 신규 자원 등록의 특징은 아래와 같다.

 

1. 클라이언트는 등록될 리소스의 URI를 모른다.

- 회원 등록 API를 살펴보자. 별도의 id를 넘기지 않는다. 즉, 등록될 리소스의 URI를 모르기 때문이다.

 

2. 서버가 새로 등록된 리소스 URI를 생성해준다.

- 1번에서 이어지는 내용이다. 이전 포스트에서 적었듯이, 등록된 리소스 URI를 생성하고, 그 값을 Location 헤더로 넘기는 것을 알 수 있다.

 

3. Collectioin

- 서버가 관리하는 리소스 디렉토리를 뜻한다. POST 기반에서는 서버가 리소스의 URI를 생성하고 관리한다(1,2번 내용). 이 API의 설계에서는 /members 가 collection이다.

 

파일 관리 시스템 - PUT 기반 등록

• 파일 목록 /files GET
• 파일 조회 /files/{filename} GET
• 파일 등록 /files/{filename} PUT
• 파일 삭제 /files/{filename} DELETE
• 파일 대량 등록 /files POST

PUT 기반 신규 자원 등록의 특징은 아래와 같다.

 

1. 클라이언트가 리소스 URI를 알고 있어야한다.

- POST 기반은 별도 id를 넘기지 않았음을 기억해보자. 하지만 파일을 등록하는 경우에는 파일명을 리소스 uri에 담아서 넘긴다.

 

2. 클라이언트가 직접 리소스의 URI를 지정한다.

- 1번과 이어지는 내용이다. 클라이언트가 URI도 알고있으며, 등록 시 직접 지정한다.

 

3. Store

- 클라이언트가 관리하는 리소스 저장소를 뜻한다. 여기서 store는 /files 이다.

 

HTML FORM 사용

• 회원 목록 /members GET
• 회원 등록 폼 /members/new GET
• 회원 등록 /members/new, /members POST
• 회원 조회 /members/{id} GET
• 회원 수정 폼 /members/{id}/edit GET
• 회원 수정 /members/{id}/edit, /members/{id} POST
• 회원 삭제 /members/{id}/delete POST

잘 모르시는 분들은 여기서는 왜 GET, POST만 쓰고 URI에 행위가 들어가냐는 의문이 있을 수 있을 것 같다.

HTTP FORM은 GET과 POST 메서드만이 사용 가능하기 때문이다. 따라서 부득이하게 URI에 행위를 표현하게 된다.

 

이렇게 URI에 행위를 표현하게 되는 것이 컨트롤 URI다.

• 동사로 된 리소스 경로를 사용
• 위 API 설계의 경우 /new, /edit, /delete가 컨트롤 URI

컨트롤 URI는 HTTP 메서드로 해결하기 애매한 경우에도 쓰이곤 한다. 즉, HTTP FORM에 국한된 이야기가 아니다.