HTTP API 설계

• HTTP API - 컬렉션
  • POST 기반 등록
  • 예) 회원 관리 API 제공
• HTTP API - 스토어
  • PUT 기반 등록
  • 예) 정적 컨텐츠 관리, 원격 파일 관리
• HTTP FORM 사용
  • 웹 페이지 회원 관리
  • GET, POST만 지원

---

API 설계 - POST 기반 등록

회원 관리 시스템

• 회원 목록 /members -> GET
  • 조건이 있다면 쿼리 파라미터에 추가해서 전달하면 된다
• 회원 등록 /members -> POST
• 회원 조회 /members/{id} -> GET
• 회원 수정 /members/{id} -> PATCH, PUT, POST
  • 보통 게시글 수정의 경우 부분이 바뀌더라도 PUT으로 일괄 변경 처리한다
• 회원 삭제 /members/{id} -> DELETE

POST - 신규 자원등록 특징

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

  • 회원등록 /members -> POST
  • POST /members

• 요청 메시지를 받은 서버가 새로 등록된 리소스의 URI를 생성해준다

  • HTTP/1.1 201 Created
    Location: /members/100

• 컬렉션 (Collection)

  • 서버가 관리하는 리소스 디렉토리
  • 서버가 리소스의 URI를 생성하고 관리한다
  • 여기서의 컬렉션은 /members

POST는 클라이언트가 서버에게 이 리소스를 등록해달라고 요청한다. 그러면 서버는 해당 리소스의 URI를 만들어서 돌려준다

---

API 설계 - PUT 기반 등록

파일 관리 시스템

• 파일 목록 /files -> GET
• 파일 조회 /files/{filename} -> GET
• 파일 등록 /files/{filename} -> PUT
  • 기존 파일이 있어도 덮어쓴다
• 파일 삭제 /files/{filename} -> DELETE
• 파일 대량 등록 /files -> POST
  • POST는 상황에 맞게 쓸수 있다. 이번 경우에는 대량 등록을 위해 사용

PUT - 신규 자원 등록 특징

등록을 위해 POST대신 PUT을 사용하고 있다. 어떤 차이점이 있을까?

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

  • 파일 등록 /files/{filename} -> PUT
  • PUT /files/start.jpg

• 클라이언트가 직접 리소서의 URI를 지정한다

• 스토어(store)

  • 클라이언트가 관리하는 리소스 저장소
  • 클라이언트가 리소스의 URI를 알고 관리한다
  • 여기서 스토어는 /files

PUT은 클라이언트가 관리하는 리소스의 URI를 지정해서 서버에게 등록해달라고 요청한다. 그러면 서버는 해당 리소스를 전달 받은 URI에 등록해준다

참고
대부분 POST기반의 Collection의 관리 시스템을 사용한다

---

HTML FORM 사용

• HTML FORM은 GET, POST만 지원한다
• AJAX 같은 기술을 사용해서 해결 가능하다 -> 회원 API 참고
• 순수 HTML + HTML FORM은 GET, POST만 지원하므로 제약이 있다

구성
-> PUT, PATCH, DELETE를 대체해야한다

• 회원 목록 /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 링크로 들어가진다 -> 그러면 HTML FORM이 나타나고 거기에 정보를 입력한다 -> <form>태그를 데이터를 입력을 하고 저장(submit 버튼을 누르면)을 하면 -> POST로 넘어가게 되는데 이때 /members/new 또는 /members 중 선택해서 하면 된다

회원 조회 & 수정 폼 & 수정

회원 목록에서 회원 링크를 하나 누르면 해당 회원의 상세 화면으로 들어가진다 이때 /members/{id}를 통해 들어가게 되는 것이다 -> 들어가서 수정 버튼을 누르면 회원 수정 폼으로 이동하게 된다. 이때는 변경이 일어나는 것이 아니라 edit으로 가는 것으로 GET을 사용한다 -> 나타난 edit FORM에서 데이터를 변경하고 저장(submit)을 하게 되면 -> 해당 HTML FORM데이터를 서버에 전송해야 하는데 이때, members/{id}/edit 또는 /members/{id}를 사용하게 된다

수정 버튼이 아니라 삭제 버튼을 누를 경우 -> /members/{id}/delete를 POST해서 삭제하게 된다. DELETE메소드가 없으므로 컨트롤 URI를 사용해야만 한다

컨트롤 URI

• GET, POST만 지원하므로 제약이 있다
• 이런 제약을 해결하기 위해 동사로 된 리소스 경로를 사용한다
• 위에서는 POST의 /new, /edit, /delete가 컨트롤 URI이다
• HTTP 메서드로 해결하기 애매한 경우 사용한다 (HTTP API 포함)

---

정리

HTTP API - Collection

• POST 기반 등록이다
• 서버가 리소스 URI를 결정한다
• 대부분 사용하는 방식이다

HTTP API - Store

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

HTML FORM 사용

• 순수 HTML + HTML form 사용
• GET, POST만 사용이 가능하다
• 컨트롤 URI를 통해 해결한다
  • 동사형 URI - /members/{id}/edit

문서(document)

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

컬렉션(Collection)

• 서버가 관리하는 리소스 디렉터리
• 서버가 리소스를 생성하고 관리한다
• /members

스토어(Store)

• 클라이언트가 관리하는 자원 저장소
• 클라이언트가 리소스의 URI를 알고 관리한다
• 서버에 등록할 때 URI를 지정해서 전달한다
• /files

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

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

원칙

기본적으로 리소스가 아닌 메서드로 접근해야 한다. 미네랄을 캐라가 있다면 캐라는 리소스가 아니므로 버리고, 타켓을 미네랄로 잡는다. 미네랄(자원)만을 가지고 리소스를 설계한다

즉, 자원인 회원, 주문이 있다면
회원(/members), 주문(/orders)을 갖추고 계층 구조로 회원의 번호(/members/{id}), 주문의 번호(/orders/{no}) 등을 구성한다. 이렇게 설계를 하고나서 GET, POST 등의 메소드로 해결이 안되는 상황일 때, 컨트롤 URI를 사용하게 된다