#6. [HTTP] HTTP API 설계 예시

- HTTP API - 컬렉션

  * POST 기반 등록

  * 예) 회원 관리 API 제공

- HTTP API - 스토어

  * PUT 기반 등록

  * 예) 정적 컨텐츠 관리, 원격 파일 관리

- HTML FORM 사용

  * 웹 페이지 회원 관리

  * GET, POST만 지원

 

회원 관리 시스템

API 설계 - POST 기반 등록

- 회원 목록 /members : GET

- 회원 등록 /members : POST

- 회원 조회 /members/{id} : GET

- 회원 수정 /members/{id} : PATCH, PUT, POST

- 회원 삭제 /members/{id} : DELETE

(다시한번 강조하지만 URI 설계는 항상 리소스를 기준으로 설계를 해야 한다.)

 

 

회원 관리 시스템

POST - 신규 자원 등록 특징

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

  * 회원 등록 /members -> POST

  * POST /members

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

  * HTTP/1.1 201 Created

    Location: /members/100

(이거 중요함!! 서버가 신규 URI 생성한다는 것을 잊지 말자!)

- 컬렉션(Collection)

  * 서버가 관리하는 리소스 디렉토리

  * 서버가 리소스의 URI를 생성하고 관리

  * 여기서 컬렉션은 /members

 

 

파일 관리 시스템

API 설계 - PUT 기반 등록

- 파일 목록 /files -> GET

- 파일 조회 /files/{filename} -> GET

- 파일 등록 /files/{filename} -> PUT

- 파일 삭제 /files/{filename} -> DELETE

- 파일 대량 등록 /files -> POST

 

 

파일 관리 시스템

PUT - 신규 자원 등록 특징

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

  * 파일 등록 /files/{filename} -> PUT 

  * PUT /files/star.jpg

- 클라이언트가 직접 리소스의 URI를 지정한다.

(이 말인 즉슨 클라이언트가 URI가 어디에 등록할지 등을 다 안다는 의미

이건 클라이언트가 모든 URI를 관리함. 그리고 이런 스타일의 관리를 스토어라고 한다.)

- 스토어(Store)

  * 클라이언트가 관리하는 리소스 저장소

  * 클라이언트가 리소스의 URI를 알고 관리

  * 여기서 스토어는 /files

 

무엇을 많이 쓸까????? 대부분 POST기반의 URI를 Collection으로 관리

 

 

HTML FORM 사용

- HTML FORM은 GET, POST만 지원

- AJAX 같은 기술을 사용해서 해결 가능

- 여기서는 순수 HTML, HTML FORM 이야기

- GET, POST만 지원하므로 제약이 있음

 

HTML FORM 사용

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

(하나의 시나리오를 써보자.

1. 회원 목록을 볼 때 /members를 타겟으로 GET 요청을 보내면 HTML 문서를 받아 볼 수 있다.

2. 회원 등록 링크를 클릭하면, /members/new URI를 타겟으로 GET 요청을 보내 FORM 관련 HTML문서를 받는다.

3. 회원 관련 정보를 입력한 후 저장 버튼을 누르면 /members/new로 GET, POST요청에 따라 다르게 동작하도록 URI를 맞춰주거나 /members를 타겟으로 POST요청 시 서버에 데이터를 저장하도록 한다.(둘중 선택)

(강사가 선호하는 스타일은 회원 등록 폼과 회원 등록의 URI를 일치시켜 주는것을 선호, 이유는 서버에 문제가 생겨서 데이터를 폼으로 전달해서 다시 보내야 하는 경우가 생기는데 이때 URI를 일치시켜주면 처리하기 편함)

4. 회원 하나를 클릭 시 /members/{id}로 GET  요청을 보내면 회원 상세 HTML 문서를 받아 본다.

5. 이 회원 상세에는 정보를 수정하는 버튼이 존재하는데 수정하기 버튼을 클릭하면 수정하기 폼으로 이동하도록 /members/{id}/edit의 GET요청을 보내 수정하는 FORM을 서버로부터 받는다.

6. 회원 수정 시에도 /members/{id}/edit, /members/{id}둘 중 하나를 선택해서 POST 요청을 보내어 수정.

7. 회원 삭제 시에도 /members/{id}/delete POST요청을 통해 (DELETE못쓰므로) 삭제 요청을 보내어 삭제 결과를 응답 받는다.

끝~ )

 

HTML FORM 사용

- HTML FORM은 GET, POST만 지원

- 컨트롤 URI

  * GET, POST만 지원하므로 제약이 있음

  * 이런 제약을 해결하기 위해 동사로 된 리소스 경로 사용

  * POST의 /new, /edit, /delete가 컨트롤 URI

  * HTTP 메서드로 해결하기 애매한 경우 사용(HTTP API 포함)

(URI 설계는 최대한 리소스를 기준으로 설계를 하고, 도저히 할 수 없을때 대체재로써 컨트롤 URI를 쓰자)

 

 

정리

- HTTP API - 컬렉션

  * POST 기반 등록

  * 서버가 리소스 URI를 결정

- HTTP API - 스토어

  * PUT 기반 등록

  * 클라이언트가 리소스 URI를 결정

- HTML FORM 사용

  * 순수 HTML + HTML form 사용

  * GET, POST만 지원

(필연적으로 컨트롤 URI가 많아질수 밖에 없다.)

 

 

정리

참고하면 좋은 URI 설계 개념

- 문서(document)

  * 단일 개념(파일 하나, 객체 인스턴스, 데이터베이스 row)

  * 예) /members/100, /files/star.jpg

 

- 컬렉션(collection)

  * 서버가 관리하는 리소스 디렉터리

  * 서버가 리소스의 URI를 생성하고 관리

  * 예) /members (POST기반 등록)

 

- 스토어(store)

  * 클라이언트가 관리하는 리소스 디렉터리

  * 클라이언트가 리소스의 URI를 알고 관리

  * 예) /files (PUT기반 등록)

 

- 컨트롤러(controller), 컨트롤 URI

  * 문서, 컬렉션, 스토어로 해결하기 어려운 추가 프로세스 실행

  * 동사를 직접 사용

  * 예) /members/{id}/delete

 

https://restfulapi.net/resource-naming 

REST Resource Naming Guide