HTTP(3) - API 설계 예

HTTP API

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

 

회원 관리 시스템

 

1. POST - 신규 자원 등록 특징 (컬렉션)

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

- POST는 기존에 없던 리소스를 새로 만드는 기능이기 때문에 서버가 새로 등록된 리소스 URI를 생성해준다.

• HTTP/1.1 201 Created
• Location: /members/ 100

 

2. PUT - 신규 자원 등록 특징 (스토어)

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

• 파일 등록 /files/{filename} -> PUT (finemane을 클라이언트가 넣어줘야한다.)
• PUT /files/star.jpg

 

 

POST는 /members라 넘기면 서버가 회원의 id를 만들고 URI도 만들어주는데 PUT으로 등록을 하면 URI를 미리 알고 관리를 해야한다.

실무에서는 POST 기반을 많이 사용한다고 한다.

 

 

 

 

HTML FORM 사용

- 기본적으로 GET이랑 POST만 지원을 한다. 따라서 제약이 존재한다.

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

제약이 있기 때문에 위와 같은 컨트롤 URL을 사용한다.

/new, /delete, /edit 등이 컨트롤 URL이다.

컨트롤 URL는 꼭 필요한 경우에만 사용해야하고 아무때나 사용하면 안된다는 조건이 있다.

 

 

 

 

 

참고할만한 URI 설계 개념

1. 문서

• 단일 개념(파일 하나, 객체 인스턴스, 데이터베이스 row)
• 예) /members/100, /files/star.jpg

2. 컬렉션(collection)

• 서버가 관리하는 리소스 디렉터리
• 서버가 리소스의 URI를 생성하고 관리
• 예) /HTTP/1.1 201 Created
•       Location: /members/100             ->      여기서 컬렉션은 /members

 

3. 스토어(store)

• 클라이언트가 관리하는 자원 저장소
• 클라이언트가 리소스의 URI를 알고 관리
• 예) PUT /files/star.jpg      ->     여기서 스토어는 files

4. 컨트롤러(controller), 컨트롤러 URI

• 문서, 컬렉션, 스토어로 해결하기 어려운 추가 프로세스 실행
• 동사를 직접 사용
• 예) /memebers/{id}/delete