HTTP API를 이용하여 HTTP URI 설계하기

HTTP API를 이용하여 URI를 설계할 때 어떤 방식을 쓰는지 예시를 통해 알아보겠습니다.

1. HTTP API - 컬렉션
- POST 메서드를 기반으로 등록하는 방식
   예) 회원 관리 API 제공

2. HTTP API - 스토어
- PUT 메서드를 기반으로 등록하는 방식
   예) 정적 컨텐츠 관리, 원격 파일 관리

3. HTML FORM 사용
- GET, POST만 지원
   예) 웹 페이지 회원 관리

 

---

 

1. HTTP API - 컬렉션

POST 메서드를 기반으로 등록하게 됩니다.

 

회원관리 시스템을 예시로 설명하겠습니다.

 

• 회원 목록 /members -> GET
• 회원 조회 /members/{id} -> GET
• 회원 등록 /members -> POST
• 회원 수정 /members/{id} -> PATCH, PUT, POST

   - PATCH : 회원의 데이터를 부분적으로 수정하기 때문에 회원 수정 시에 주로 쓰입니다.

   - PUT : 전체데이터를 덮어쓰기 때문에 회원 정보 수정 시에는 적합하지 않습니다. 여러 정보 중 하나의 데이터라도 빠뜨리고 전송하게 되면 해당 데이터는 유실되기 쉽기 때문입니다. 다만, 게시글 수정 같은 경우에는 부분 수정보다는 게시글의 전체 데이터를 다시 수정하는 경우가 많기 때문에 PUT이 적합할 수도 있습니다.

   - POST : PATCH이나 PUT을 사용하기 애매할때는 POST를 사용하면 됩니다.
• 회원 삭제 /members/{id} -> DELETE

 

POST를 사용하여 신규 자원 등록 시의 특징
- 서버가 리소스의 URI를 만들어주기 때문에 클라이언트는 등록될 리소스의 URI를 몰라도 됩니다.

 

이러한 방식을 컬렉션(Collection)이라고 합니다.

 

컬렉션
- 서버가 리소스의 URI를 생성하고 리소스 디렉토리를 관리합니다.
   예시) HTTP/1.1 201 Created Location: /members/100
- POST 메서드를 사용합니다.
- 여기서 컬렉션은 /members 입니다.

 

 

2. HTTP API - 스토어

POST 메서드를 기반으로 등록하게 됩니다.

 

파일관리 시스템이 스토어 방식에 적합합니다.

• 파일 목록 /files -> GET
• 파일 조회 /files/{filename} -> GET
• 파일 등록 /files/{filename} -> PUT

   - PUT 메서드는 리소스의 URI를 알고 있을 때 사용하게 됩니다. 파일관리 시에는 클라이언트가 파일의 이름을 알고 있기 때문에 PUT 메서드를 사용하여 파일이 존재할 때는 덮어쓰고 없으면 새로 생성하는 PUT 메서드가 적합합니다.
• 파일 삭제 /files/{filename} -> DELETE
• 파일 대량 등록 /files -> POST

 

PUT을 사용하여 신규 자원 등록 시의 특징
- 클라이언트가 등록될 리소스의 URI를 알고 있어야 합니다.

 

이러한 방식을 스토어라고 합니다.

스토어
- 클라이언트가 리소스 저장소를 관리합니다.
- 파일 등록시 클라이언트가 직접 리소스의 URI를 지정해야하는 PUT 메서드를 사용합니다.
- /files/{filename} 와 같은 URI를 사용합니다.
   예) PUT /files/star.jpg
- 여기서 스토어는 /files

 

 

 

 

 

3.HTML FORM 사용

HTML FORM은 GET, POST만 지원합니다.
HTTP API 인 AJAX 같은 기술을 사용해서 다른 메서드도 사용할 수 있지만

여기서는 순수 HTML, HTML FORM을 사용하여 GET, POST만을 이용해야 하는 제약이 있다는 가정입니다.

 

• 회원 목록 /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

 

HTML FORM은 GET, POST만 지원하므로 제약이 있습니다.

이런 제약을 해결하기 위해 동사로 된 리소스 경로를 사용합니다.

이것을 컨트롤 URI라고 합니다.

 

컨트롤 URI
- 동사가 포함된 리소스 경로
- POST의 /new, /edit, /delete가 컨트롤 URI
- HTTP 메서드로 해결하기 애매한 경우 사용
- HTTP API에서도 사용하는 경우 多

 

---

 

참고하면 좋은 URI 설계 개념 정리

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

컬렉션(collection)
• 서버가 관리하는 리소스 디렉터리
• 서버가 리소스의 URI를 생성하고 관리
• 예) /members

스토어(store)
• 클라이언트가 관리하는 자원 저장소
• 클라이언트가 리소스의 URI를 알고 관리
• 예) /files

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

 

 

 

참고 자료 : 인프런 - 모든 개발자를 위한 HTTP 웹 기본 지식 ( 김영한 ) https://inf.run/WbA7