[HTTP] HTTP API 설계 방법 기초

---

POST 기반 등록 방식

회원의 [ic]CRUD[/ic]를 예로 들면

그림과 같이 설계할 수 있습니다.

Update

수정에 관해서는 3가지 메서드 중에 고려할 수 있는데

회원 정보가 많아질수록 [ic]PUT[/ic]을 사용하면 회원정보 싹 다 새로 넣어야 되서

시간과 자원을 많이 소모할 수 있습니다.

왠만하면 [ic]PATCH[/ic]를 사용하며

게시물 수정같은 글을 통채로 갈아끼워 넣어야 할 때는 [ic]PUT[/ic]을 쓰기도 합니다.

 

서버에서 리소스를 생성하고 관리

클라이언트는 등록될 리소스의 [ic]URI[/ic]를 모릅니다.

 

회원을 등록하고싶을 때 [ic]/members[/ic]만 넘기면

서버에서 알아서 리소스 [ic]URI[/ic]를 생성해서 등록해줍니다.

포인트는 서버가 알아서 리소스를 만든다는 점입니다.

 

여기서 [ic]/members[/ic]를 Collection이라고 부릅니다.

---

PUT 기반 등록 방식

파일의 CRUD를 예로 들면

그림과 같이 설계할 수 있습니다.

Update

파일은 따로 수정할 필요 없이 등록([ic]PUT[/ic])만 하면 되므로 고민할 필요가 없습니다.

 

클라이언트에서 리소스를 생성하고 관리

[ic]POST[/ic] 기반 등록 방식과 반대로 [ic]PUT[/ic]은 클라이언트에서 [ic]리소스 URI[/ic]를 생성하고 관리합니다.

[ic]/files/100[/ic]이란 리소스를 클라이언트가 알고있는 상태에서 보냅니다.

 

여기서 [ic]/files[/ic]를 [ic]Store[/ic]라고 부릅니다.

 

위의 [ic]POST[/ic] 방식과 다른 점이므로 각 [ic]Entity의 특성[/ic]에 맞게 등록 방식을 다르게 적용하면 됩니다.

실무에서는 [ic]POST[/ic] 방식을 대부분 선호합니다.

정말 일부에서 파일 업로드 같은 곳에서는 [ic]PUT[/ic] 방식을 사용합니다.

---

HTML FORM 사용

[ic]HTML form 태그[/ic]는 [ic]GET[/ic], [ic]POST[/ic] 두개밖에 지원하지 않습니다.

이를 이용해 [ic]API[/ic]를 설계해야 한다면

이렇게 설계해야 합니다.

 

서버에서 HTML FORM, 틀 까지 전송

위의 두 방식과 달리

서버에서 탬플릿엔진까지 가동하여 [ic]HTML파일[/ic]을 전송하는 것이므로

[ic]FORM 정보[/ic]까지 따로 전송해야 합니다.

그래서 [ic]URI[/ic]가 겹치는 현상이 발생하므로 어쩔수 없이 [ic]컨트롤 URI[/ic]를 사용할 수 밖에 없습니다.

---

설계 방법

1. 리소스를 바탕으로 설계합니다.

회원은 [ic]members[/ic], 물품은 [ic]items[/ic]로 컬렉션으로 설계하도록 합니다.

되도록 동사는 사용하지 않습니다.

 

2. 상세 물품, 즉 문서는 컬렉션 안에 번호로 설계합니다.

단일 회원을 조회하고 싶다면 [ic]members/{id}[/ic], 물품 한개를 조회하고 싶다면 [ic]items/{id}[/ic]로 조회합니다.

컬렉션을 사용한 후에 뒤에 단일 개념이 오는 구조입니다.

 

3. 1, 2번으로 해결이 안되는 상황이면 컨트롤 [ic]URI[/ic]로 설계합니다.

기본적인 [ic]CRUD[/ic]는 위의 방식으로 해결되지만, 배달하라는 명령 등 복합적인 로직이 이루어질 때에는

[ic]URI[/ic]을 설계할 수 있는 방법이 별로 없습니다.

[ic]HTML form 방식[/ic]에서만 적용되는것이 아닌, [ic]HTTP API 설계[/ic]할 때에도 똑같은 어려움이 발생할 때가 있습니다.

이 때 [ic]컨트롤 URI[/ic]을 사용하여 설계해야합니다.

 

---

URI 설계 개념

문서 document

파일 한개, 객체 인스턴스, 데이터베이스의 row 등 단일 개념을 문서라고 합니다.

[ic]/members/100[/ic], [ic]/files/hyeok.jpg[/ic]

 

컬렉션 collection

서버가 관리하는 리소스 디렉터리입니다. 여기서 리소스의 URI를 생성하고 관리합니다.

[ic]POST[/ic] 방식으로 등록할 때 컬렉션을 사용합니다.

 

스토어 store

클라이언트가 관리하는 리소스 디렉터리입니다.

[ic]PUT[/ic] 방식으로 등록할 때 스토어를 사용합니다.

 

컨트롤러 controller, Controll URI

위의 3개를 적용하면서도 [ic]URI 설계[/ic]가 어려운 추가 프로세스 실행 과정은

동사를 직접 사용하여 해결합니다.

[ic]/members/{id}/process[/ic]

---

참조

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

REST Resource Naming Guide