17. 모든 개발자를 위한 HTTP 웹 기본 지식 - [HTTP 메서드 활용] -HTTP API 설계 예시

<HTTP API 설계 과정 TIP>

1. 리소스를 식별하여 리소스만으로 URI를 설계한다.
2. 문서, 컬렉션, 스토어로 해결하기 어려운 상황의 경우, 컨트롤 URI를 사용한다.

---

🧑🏻‍🏫 HTTP API 설계 예시 3가지

• POST 기반으로 등록, PUT기반으로 등록하는 2가지 경우의 특징을 아는 것이 중요하다.
• 대부분 POST 기반 신규 자원 등록 방법(컬렉션)을 많이 사용한다.

1) HTTP API - 컬렉션

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

2) HTTP API - 스토어

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

3) HTML FORM 사용

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

---

👩🏻‍💼 API 설계 - POST 기반 등록

회원 관리 시스템

1. 회원목록 : /members  ➡️ GET
2. 회원등록 : /members  ➡️ POST
3. 회원조회 : /members/{id}  ➡️ GET
4. 회원수정 : /members/{id}  ➡️ PATCH, PUT, POST
5. 회원삭제 : /members/{id}  ➡️ DELETE

Q. 회원 수정은 PATCH, PUT, POST 중 무엇으로 구현하는 것이 좋을까?

 

A. 개념적으로는 리소스 부분 변경인 PATCH로 하는 것이 가장 좋다.

기존 리소스를 덮어써도 문제가 없는 경우, PUT을 사용할 수는 있지만 그런 경우는 거의 없다. 클라이언트에서 회원의 모든 데이터(id, 이름, email 등)을  다 보내야하기 때문이다.

• 게시글 수정같은 경우, 완전히 덮어써도 문제X

애매한 경우, POST를 쓰면 된다.

 

👀 POST - 신규 자원 등록 특징

• 클라이언트는 등록될 리소스의 URI를 모른다.
• 회원 데이터를 서버에 요청하고 서버가 알아서 회원을 식별해서 URI를 만들어준다.

(클라이언트)
회원등록 : /members  ➡️ POST
POST /memebers

• 클라이언트가 결정하는 게 아니라 서버가 새로 등록된 리소스 URI를 생성해준다.(중요!)

(서버)
HTTP/1.1 201 Created
Location : /members/100

컬렉션(Collection)

/members

• 서버가 관리하는 리소스 디렉토리이다.
• 리소스의 URI를 생성하고 관리한다.

---

📝 API 설계 - PUT 기반 등록

파일 관리 시스템

1. 파일목록 : /files  ➡️ GET
2. 파일조회 : /files/{filename} ➡️ GET
3. 파일등록 : /files/{filename} ➡️ PUT
4. 파일삭제 : /files/{filename} ➡️ DELETE
5. 파일대량 등록 : /files ➡️ POST

파일 등록같은 경우는 해당 파일이 있으면 기존 것을 덮어써야하기 때문에, PUT을 쓴다.

👀 PUT - 신규 자원 등록 특징

파일등록 : /file/{filename}  ➡️  POST
PUT /files/star.jpg

• 클라이언트가 리소스 URI를 알고 있어야 한다.
• 클라이언트가 직접 리소스의 URI를 지정한다.
• 클라이언트가 직접 리소스를 관리해야 한다.

스토어(Store)

/files

• 클라이언트가 관리하는 리소스 저장소
• 클라이언트가 리소스의 URI를 알고 관리

---

📑 API 설계 - HTML FORM 사용

회원 관리 시스템

1. 회원목록 : /members  ➡️  GET
2. 회원등록 폼 : /members/new  ➡️  GET
3. 회원등록 : /members/new, /members  ➡️  POST
4. 회원조회 : /members/{id}  ➡️  GET
5. 회원수정 폼 : /members/{id}/edit  ➡️  GET
6. 회원수정 : /members/{id}/edit, /members/{id}  ➡️  POST
7. 회원삭제 : /members/{id}/delete  ➡️  POST

• 회원 등록 폼과 회원 등록의 URL을 일치하는 것을 추천한다!
• HTML FORM을 사용하지 않는다면 회원 삭제의 URI는 /members/{id} DELETE로 설계하면된다.
• 하지만순수한 HTML과 HTML Form은 GET, POST만 지원하기 때문에 제약이 있다.
• 제약을 해결하기 위해 동사로 된 리소스 경로를 사용을 하는데 이걸 컨트롤 URI이라 한다.

👀  HTML FORM 특징

1. HTML FORM은 GET, POST만 지원하므로 제약이 있다.
2. 제약을 해결하기 위해 컨트롤 URI 사용

● 컨트롤 URI

• GET, POST 만 지원하는 제약을 해결하기 위해 동사로 된 리소스 경로 사용
• → POST의 /new, /edit, /delete가 컨트롤 URI
• HTTP 메서드로 해결하기 애매한 경우 사용!! (HTML FORM을 사용하지 않더라도 쓸 수 O)

---

🧹 정리

1) HTTP API - 컬렉션

• POST 기반 등록
• 서버가 리소스 URI 결정

2) HTTP API - 스토어

• PUT 기반 등록
• 클라이언트가 리소스 URI 결정

3) HTML FORM 사용

• 순수 HTML + HTML form 사용
• GET, POST만 지원 → 컨트롤 URI로 해결

---

👨🏻‍💻 참고하면 좋은 URI 설계 개념

● 문서(document)

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

● 컬렉션(Collection)

• 서버가 관리하는 리소스 디렉토리
• 서버가 리소스의 URI를 생성, 관리
• /members

● 스토어(Store)

• 클라이언트가 관리하는 리소스 디렉토리
• 클라이언트가 리소스의 URI를 알고 관리
• /files

● 컨트롤러(Controller), 컨트롤 URI

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

주로 컬렉션을 많이 사용하고, 파일 /게시판 같은 경우에 스토어를 사용할 수 있다.

문서, 컬렉션, 스토어로 해결하기 어려운 추가 프로세스를 실행할 때, 컨트롤 URI를 사용한다.

 

[참고] https://restfulapi.net/resource-naming/

---

🙋🏻‍♂️ Q&A

Q. /members/{id} 같은 API URL에서 {id}에는 특정 회원을 식별할 수 있는 값인 회원 테이블의 PK 값이 들어가는 건가요?, 만약 PK가 id, email 이라면 어떤 식으로 URL을 설계해야 하는가?

 

A. API의 리소스 설계와 실제 애플리케이션의 물리적 설계는 개념상 서로 분리되는 것이 맞다.

따라서 {id}를 실제 DB의 PK를 사용해도 되고, 사용자의 로그인 id, 또다른 개념을 넣어도 무방하다.

만약 PK가 2개의 컬럼을 합한 값이라면 하나의 유니크한 값을 만들어 사용하는 것이 더 좋다.

 

[출처] https://www.inflearn.com/questions/163718

---

Q. 특정 데이터를 삭제해야할 때 DB에서 물리적으로 지우지 않고 useYN같은 삭제 여부 필드를 두기도 합니다. 비즈니스 상으로는 삭제이지만 실제 DB 데이터를 지우는 것이 아니라 useYN 필드 값을 Y에서 N으로 수정하는 것이니 DELETE 메서드가 아니라 PATCH 메서드를 쓰는 것이 더 적합하지 않나요?

 

A. 실무에서도 DELETE를 하는 것은 매우 조심스럽게 생각해야 한다.

 

HTTP로 제공하는 인터페이스는 내부 구현과는 분리되도록 작업해야 한다.

그래서 내부에서 실제 리소스를 삭제하든, useYN을 사용하든 구현할 때 적절한 방안을 선택하면 된다.

따라서 외부에는 DELETE 메서드로 제공하고 내부에서는 실제 DB를 사용하지 않고 useYN의 값을 변경하는 것처럼 사용해도 된다.

[출처] https://www.inflearn.com/questions/110136

---

Q. 데이터 전송의 경우 2가지 방식중 어떤 방식을 실무에서 선호하는가?

A. 두 방식 모두 잘 사용하고 다만 사용하는 상황이 서로 다를 뿐이다.

form 과 별개로 사용자와의 상호작용을 위해 API를 호출하여 데이터를 내려받아야 하는 경우, 주로 비동기통신 방식을 사용한다.

 

[출처] https://www.inflearn.com/questions/488416

---

Q. 서버에서 URI를 생성하여 넘겨주면 React, Vue 같은 프론트에서는 어떻게 이를 처리하나요?

 

A. React, Vue와 연동할 경우, HTML 파일에 대한 처리를 클라이언트가 하기 때문에 백엔드에서 뷰 파일을 처리하는 부분이 필요없다. 백엔드에서는 데이터/결과값을 담은 객체를 반환하고 이를 프론트에서 받아서 처리한다.

 

[출처] https://www.inflearn.com/questions/511688

 

참고 : https://hseungyeon.tistory.com

 

위 자료는 김영한님의 ‘모든 개발자를 위한 HTTP 웹 기본 지식’ 강의를 참고하여 작성하였습니다.
https://www.inflearn.com/course/http-웹-네트워크/dashboard