모든 개발자를 위한 HTTP 웹 기본 지식 강의 수강 후, 정리한 글입니다.

목차

1. 클라이언트에서 서버로 데이터 전송
2. HTTP API 설계 예시
3. URI 설계의 좋은 Practice

1. 클라이언트에서 서버로 데이터 전송

1) 데이터 전송 방식 2가지

① 쿼리 파라미터(query parameter)

• GET
• 예시) 정렬 필터(검색어)

② 메시지 바디(message body)

• POST, PUT, PATCH
• 회원가입, 상품 주문, 리소스 등록, 리소스 변경

2) 데이터 전송 상황 4가지

① 정적 데이터 조회

• 이미지, 정적 텍스트 문서
• GET, 쿼리 파라미터 없이 리소스 경로로 단순하게 조회가 가능하다.
  

② 동적 데이터 조회

• 검색, 게시판 목록에서 정렬 필터(검색어)
• GET, 쿼리 파라미터를 사용해서 데이터를 전달한다.
  

③ HTML form 이용

• 회원가입, 상품 주문, 데이터 변경
• POST, 데이터를 저장하기 위해 메시지 바디를 통해 key=value의 쿼리 파라미터 형식으로 데이터를 전달한다. 이때, abc김 → abc%EA%B9%80 처럼 전송 데이터를 url encoding 처리한다.
  
• GET, 데이터를 조회하기 위해 사용할 수 있다. GET 메서드를 리소스 변경이 발생하는 곳에는 사용하면 안되니 주의하자.
  
• multipart/form-data, 주로 이미지 파일 업로드와 같은 binary form data에 사용한다.
  

④ HTML API 이용

• 회원가입, 상품 주문, 데이터 변경
• 서버 to 서버: 백엔드 시스템 통신
• 앱 클라이언트: 아이폰, 안드로이드
• 웹 클라이언트: java script를 통한 통신에 사용(AJAX 통신)

• POST, PUT, PATCH: 메시지 바디를 통해 데이터를 전송한다.
• GET: 쿼리 파라미터로 데이터 전달하여 조회한다.
• Content-Type: application/json: text, xml, json 등 사실상 표준으로 주로 사용한다.
  

2. HTTP API 설계 예시

1) 회원 관리 시스템

회원 관리 시스템의 API를 설계한다고 해보자.
먼저 회원 관리에 관한 것이니 컬렉션을 /members로 하겠다.

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

2) 파일 관리 시스템

다음으로 파일 관리 시스템의 API를 설계해보자.
파일 관리에 관한 것이니 스토어는 /files로 하겠다.

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

여기서, 회원 등록에는 POST, 파일 등록에는 PUT, 파일 대량 등록에는 POST를 사용하는 이유가 궁금해져야 한다.

• 회원 등록에 POST를 사용한 이유: 회원 등록 시에 클라이언트는 등록될 리소스의 URI를 모르기 때문이다. /members
• 파일 등록에 PUT을 사용한 이유: 클라이언트가 이미 등록될 리소스의 URI를 알고 있기 때문이다. URI가 파일명으로 저장되는데, 파일명을 클라이언트가 보내준다. /files/{filename}
• 파일 대량 등록에 POST를 사용한 이유: PUT 메서드를 같은 URI로 1개의 파일 등록에 사용했기 때문에 임의로 POST 메서드는 파일 대량 등록에 사용하겠다는 목적을 설정한 것이다.

URI /files, method POST를 사용하고 그리고 보안이나 충돌 방지 등의 이유로 파일명을 랜덤으로 생성한다면, PUT, POST의 2가지 API를 만들지 않고 POST 하나로 처리할 수 있을 것 같기도 하다.

3) HTML FORM

• 순수 HTML
• HTML FORM은 GET, POST만 지원하므로 제약 존재
• 제약 해결 방법: 동사로된 리소스 경로 사용
  POST의 /new, /edit, /delete 컨트롤 URI
• HTTP 메서드로 해결하기 애매한 경우에 사용

3. URI 설계의 좋은 Practice

컬렉션(Collection)

POST기반. 서버가 관리하는 리소스 디렉터리로, 서버가 리소스의 URI를 생성하고 관리한다. 예시) /members

스토어(Store)

PUT기반. 클라이언트가 관리하는 리소스 저장소로, 클라이언트가 리소스의 URI를 알고 관리한다. 예시) /files

문서(Document)

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

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

위의 상황으로 해결하기 어려운 추가 프로세스 실행, 동사를 사용
예시) /members/{id}/delete