HTTP API 설계를 몇 가지 예시를 통해 한 번 알아봅시다! 아래 3가지 예시를 다루겠습니다.

1. HTTP API - 컬랙션

• POST 기반 등록
• 예) 회원 관리 API 제공

2. HTTP API - 스토어

• PUT 기반 등록
• 예) 정적 컨텐츠 관리, 원격 파일 관리

3. HTML FORM 사용

• 웹 페이지 회원 관리
• GET, POST만 지원

이제 하나씩 살펴 봅시다.

---

회원 관리 시스템(컬렉션)

회원 관리 시스템을 만들어야 한다고 가정하자. 이때, 아래와 같이 URI을 설계할 수 있다.

API 설계 - POST 기반 등록

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

회원 목록을 조회하는 경우는 /members를 이용해 회원 데이터를 JSON 형식으로 보내주면 된다. 만약 정렬을 원한다면, 정렬 조건을 쿼리 파라미터에 넣어 보내면 된다.

회원 등록은 POST를 이용한다.

회원 조회는 /members 아래에 회원의 id를 넣어주면 GET을 통해 얻어 올 수 있다. 회원 삭제도 마찬가지.

회원 수정 부분을 살펴보면 PATCH를 주로 이용하는데, 부분 수정을 할 수 있기 때문이다. PUT을 이용하여 수정하려면 모든 회원 정보를 보내야한다. 따라서 PUT 은 게시글 수정과 같이 글 전체를 수정하는 경우 사용할 수 있다.

POST - 신규 자원 등록 특징

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

• 회원 등록 : /members → POST
• POST /members

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

HTTP/1.1 201 Created
Location: /members/100

✔ 컬렉션(Collection)

• 위와 같은 형식을 컬렉션이라 한다.
• 서버가 관리하는 리소스 리렉토리
• 서버가 리소스의 URI를 생성하고 관리
• 여기서 컬렉션은 /members

---

파일 관리 시스템(스토어)

이번에는 PUT 기반의 API를 설계해보자.

API 설계 - PUT 기반 등록

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

파일 등록하는 부분을 살펴보자. 클라이언트가 파일을 등록하기 때문에 filename은 클라이언트가 알고 있다. 이때 PUT을 사용한다.
PUT은 리소스가 없으면 생성하고, 존재하면 기존의 리소스를 덮어버린다. 이와 같은 경우는 PUT 메서드가 제격이다!

PUT - 신규 자원 등록 특징

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

• 파일 등록 : /files/{filename} → PUT
• PUT /files/star.jpg

✔ 클라이언트가 직접 리소스의 URI를 지정한다.
✔ 스토어(Store)

• 위와 같은 형식을 스토어라고 한다.
• 클라이언트가 리소스의 URI를 알고 관리
• 여기서 스토어는 /files

대부분 POST기반의 컬렉션을 사용한다. PUT을 사용하는 비중은 매우 적다.

---

HTML FORM 사용

HTML FORM은 기본적으로 GET, POST만 지원한다.

물론, AJAX 같은 기술을 사용해 위의 회원 API에서 사용되는 메서드들을 모두 사용할 수 있긴하다. 여기서 이야기하는 것은 순수 HTML, HTML FORM을 의미한다.

API 설계

기능	URI	Method
회원 목록	/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

회원 등록 버튼을 누르면, /members/new 라는 곳으로 들어가게 된다. 이때 회원 등록 폼을 GET으로 가져온다. 여기서 회원 정보를 입력하고 저장(제출) 버튼을 누르면 POST로 넘어가게 된다. 이때 위의 표에서 보는 것처럼 두 가지 URI 중 하나를 선택해 사용하면 된다(보통 GET과 맞추는 것을 선호).
회원 수정도 위와 같은 과정으로 진행된다.

회원 삭제의 경우, DELETE를 사용하지 못하기 때문에 컨트롤 URI 를 사용한다.

컨트롤 URI

✔ HTML FORM은 GET, POST만 지원하므로 제약이 있다.
✔ 이런 제약을 해결하기 위해 동사로 된 리소스 경로를 사용한다.
✔ 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

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

---

참고

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