HTTP 메서드, HTTP API 만들어보기, HTTP 메서드(GET/POST/PUT/PATCH/DELETE) HTTP 메서드의 속성, HTTP 메서드 활용, 클라이언트에서 서버로 데이터 전송, HTTP API 설계 예시

  출처 : 인프런 - 모든 개발자를 위한 HTTP 웹 기본 지식(유료) / 김영한님

  유료 강의이므로 정리에 초점을 두고 코드는 일부만 인용  

https://inf.run/8ZEU8

---

1. HTTP API 만들어보기

1) 요구사항

(1) 회원 정보 관리 API 생성

• 회원 목록 조회
• 회원 조회
• 회원 등록
• 회원 수정
• 회원 삭제

2) 설계

(1) 좋은 URI 설계는 리소스와 행위를 분리 하는 것

• URI는 리소스만 식별
• 리소스와 해당 리서스를 대상으로 하는 행위를 분리(이상적인 개념)
• 회원을 등록하고 수정하고 조회하는 것이 리소스가 아니라 회원이라는 개념 자체가 리소스
• 회원을 등록하고 수정하고 조회하는 등의 행위는 모두 배제하고 회원이라는 리소스만 식별(회원 리소스를 URI에 매핑)

(2) API URI 설계

구분	좋지 않은 설계	좋은 설계
회원 목록 조회	/read-member-list	/members
회원 조회	/read-member-by-id	/members/{id}
회원 등록	/create-member
회원 수정	/update-member
회원 삭제	/delete-member

• 회원 조회, 등록, 수정, 삭제dml URI가 동일한 모두 동일 구분 하는 방법은 HTTP메서드가 역할을 해줌

** 참고

• 계층 구조상 상위를 컬렉션으로 보고 복수단어 사용을 권장함(member -> members)

---

2. HTTP 메서드

1) HTTP  메서드 종류

(1) 주요 메서드

• GET : 리소스 조회
• POST : 요청 데이터 처리(주로 등록에 사용)
• PUT : 리소스를 대체, 해당 리소스가 없으면 생성
• PATCH : 리소스를 부분 변경
• DELETE : 리소스 삭제
• 최근 스펙에는 리소스가 Representation(표현)으로 변경 됨

(2) 기타 메서드

• HEAD : GET과 동일하지만 메시지 부분을 제외하고 상태 줄과 헤더만 반환
• OPTIONS : 대상 리소스에 대한 통신 가능 옵션(메서드)을 설명(주로 CORS에서 사용)
• CONNECT: 대상 리소스로 식별되는 서버에 대한 터널을 설정, 거의 사용 안함
• TRACE : 대상 리소스에 대한 경로를 따라 메시지 루프백 테스트를 수행, 거의 사용 안함

2) GET

(1) 설명

• 리소스 조회
• 서버에 전달하고 싶은 데이터는 query(쿼리 파라미터, 쿼리 스트링)를 통해서 전달
• 메시지 바디를 사용해서 데이터 전달이 가능하지만 지원하지 않는 곳이 많아서 실무에서는 권장하지 않음

(2) GET, 리소스 조회 동작

1. 클라이언트가 GET메시지를 서버에 요청
2. 서버가 메시지를 분석하여 조회 후 응답 메시지를 만듦
3. 응답 메시지(응답 데이터)를 만들어서 클라이언트에 전송

GET, 리소스 조회 동작

 

3) POST

(1) 설명

• 요청 데이터 처리
• 메시지 바디를 통해 서버로 요청 데이터를 전달
• 서버는 메시지 바디를 통해 들어온 데이터를 처리하는 모든 기능을 수행
  (서로 약속이 되어있어야 함)
• 주로 전달된 데이터로 신규 리소스를 등록 하거나, 프로세스 처리에 사용
  (주로 등록에 사용)

(2) POST, 리소스 등록

1. 클라이언트와 서버가 /members로 요청하였을 때 어떻게 처리할 것인지 약속이 되어있어야 함.
2. 클라이언트가 필요한 데이터를 /members로 전송
3. 서버가 데이터를 약속된 처리 방법으로 처리 후 신규 리소스 식별자를 생성
4. 응답 데이터를 생성하여(신규 생성된 리소스의 경로를 포함, Location) 클라이언트에 전달

POST, 리소스 등록

 

(3) POST는 모든 것이 다 가능함

• 스펙: 대상 리소스가 리소스의 고유한 의미 체계에 따라 요청에 포함된 표현을 처리하도록 요청함(구글 번역)
• 리소스 URI에 POST요청이 오면 요청 데이터를 어떻게 처리할지 리소스마다 따로 정해야 함(약속) -> 정해진 것이 없음
• HTML 양식에 입력 된 필드와 같은 데이터 블록을 데이터 처리 프로세스에 제공 -> HTML FORM에 입력된 정보로 회원 가입, 주문 등에서 사용
• 게시판, 뉴스 그룹, 메일링 리스트, 블로그 또는 유사한 기사 그룹에 메시지 게시 -> 게시판 글쓰기, 댓글 달기 등
• 서버가 아직 식별하지 않은 새 리소스 생성 -> 신규 주문 생성 등
• 기존 자원에 데이터 추가 -> 한 문서 끝에 내용을 추가하기 등

(4) POST 정리

• 새 리소스를 생성(등록) : 서버가 아직 식별하지 않은 새 리소스를 생성
  
• 요청 데이터를 처리
  
  • 단순히 데이터를 생성하거나, 변경하는 것을 넘어서 프로세스를 처리해야 하는 경우
  • 예) 결제완료 -> 배달시작 -> 배달완료 처럼 프로세스의 상태가 변경되는 경우 등
  • POST의 결과로 새로운 리소스가 생성되지 않을 수 있음(URI 설계시 리소스 만으로 설계가 어려울 때 컨트롤URI를 사용함)
  • 예) POST /orders/{orderId}/start-delivery(컨트롤 URI - 보통POST를 많이 사용함)
• 다른 메서드로 처리하기 애매한 경우
  
  • 조회 데이터를 넘겨야 하는데 GET 메시지를 사용하기 어려운 경우
  • 애매하면 POST를 사용
• 가급적 조회 할 때는 get을 쓰는 것이 유리함 (서버끼리 약속이 되어있음 - 캐싱)
• 그 외에 데이터가 변경되거나 프로세스가 진행되거나 정말 어쩔수 없는 경우에 POST를 사용

3) PUT

(1) 설명

• 리소스를 완전히 대체, 수정하는 것이 아니라 갈아 치우는 것
• 리소스가 있으면 대체하고 없으면 생성 즉, 덮어쓰기와 동일함
  
• 클라이언트가 리소스의 위치를 알고 URI를 지정함 - POST와의 차이점
  (메시지에 PUT /members/100 처럼 위치를 지정함)

(2) 리소스가 있는 경우

• 클라이언트가 지정한 리소스의 위치에 모든 필드의값을 입력하여 데이터를 전송
• 서버의 리소스가 완전히 대체됨

리소스 대체

 

(3) 주의! 데이터를 부분 전송해도 완전히 대체됨

• 클라이언트가 지정한 리소스의 위치에 보내는 데이터가 서버 데이터와 일치한 부분만 수정 되는 것이아님
• 즉, 클라이언트가 보낸 내용으로 기존 내용은 없어지고 완전히 데이터가 대체됨

데이터를 부분 전송해도 완전히 대체됨

 

(4) 리소스가 없는 경우

• 클라이언트에 지정한 리소스가 서버에 없는 경우 신규 리소스를 생성

리소스가 없으면 신규 리소스를 생성함

4) PATCH

(1) 설명

• 리소스를 부분 변경(수정)
• 클라이언트가 서버와 일치하는 필드 내용만 보내면 일치하는 부분만 변경
• 패치가 지원이 안되는 서버들이 있을 경우에는 POST를 사용

5) DELETE

(1) 설명

• 리소스를 제거함

---

3. HTTP 메서드의 속성

1) 속성

(1) 종류

• 안전 - Safe Methods
• 멱등 - Idempotent Methods
• 캐시가능 - Cacheable Methods

출처: https://ko.wikipedia.org/wiki/HTTP

 

(2) 안전, Safe

• 호출해도 리소스를 변경하지 않음
• 계속 호출해서 로그 같은게 쌓여 장애가 발생하는 등의 부분은 고려대상이 아님 즉, 해당 리소스의 변화만 고려했을 때 안전하다는 뜻

(3) 멱등, Idempotent

• 몇번을 호출하든 결과가 똑같음
• f(f(x)) = f(x)

(4) 메서드 별 멱등 비교

• GET : 몇 번을 조회하든 같은 결과가 조회
• PUT : 같은 결과가 나오는 요청을 여러번 하여도 최종 결과가 같음
• DELETE : 삭제 요청을 여러번 하여도 삭제된 결과는 같음
• POST(멱등이 아님) : 두 번 호출하면 같은 결과가 중복해서 발생할 수 있음(예시 - 중복결제)

(5) 멱등의 활용

• 자동 복구 메커니즘
• 서버가 정상 응답을 못주었을 때, 클라이언트가 같은 요청을 다시 해도 되는지 판단의 근거가 됨

(6) 멱등이 아닌 케이스

• 재요청 중간에 다른곳(외부적인 요인)에서 리소스가 변경됨
• 멱등은 외부 요인으로 중간에 리소스가 변경 되는 것까지 고려하지 않음, 즉 내가 동일한 요청을 계속 했을 때 결과가 같은 것이 멱등임

(7) 캐시가능, Cacheable

• 웹브라우저가 내부(로컬pc, 캐시서버 등)에 리소스를 저장하는 것 (추후 자세히 다룰 예정)
• GET, HEAD, POST, PATCH가 캐시가 가능하지만 실제로는 GET, HEAD 정도만 캐시로 사용
• POST, PATCH는 본문 내용까지 캐시 키로 고려해야 하는데 구현이 쉽지 않음

---

4. HTTP 메서드 활용 - 클라이언트에서 서버로 데이터 전송

1) 전달 방식

(1) 쿼리 파라미터를 통한 데이터 전송

• GET
• 주로 정렬, 필터(검색어)

(2) 메시지 바디를 통한 데이터 전송

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

2) 상황별 데이터 전송

(1) 정적 데이터 조회

• 이미지, 정적 텍스트 문서 등
• 조회이므로 GET을 사용
• 정적 데이터는 일반적으로 쿼리 파라미터 없이 리소스 경로로 단순하게 조회가 가능함

 

(2) 동적 데이터 조회

• 주로 검색, 게시판 목록에서 정렬, 필터(검색어) 등
• 조회 조건을 줄여주는 필터(검색어), 조회 결과를 정렬하는 정렬 조건에 주로 사용
• 조회이므로 GET을 사용
• 쿼리 파라미터를 사용해서 데이터를 전달
• GET은 메시지 바디를 사용하여 데이터를 전송 하는 것은 권장하지 않음

 

(3-1) HTML Form 데이터 전송

• 요청할 데이터를 HTML Form Tag로 전송하면 웹브라우저가 HTTP 메시지를 만들어서 전송

(3-2) POST 전송 - 저장

• 요청할 데이터들을 HTTP 메시지를 생성하여(쿼리파라미터와 유사한 형식, key=value) HTTP body에 담아 서버에 전송
• 데이터를 저장할 형식을 Content-Type에 표시함
• 'username=kim&age=20'과 같은 형식을 'application/x-www-form-urlencoded'라고 웹 서버간에 대부분 약속이 되어있음
• urlencoded : 한글 같은거 들어가면 인코딩 되어서 넘어감

 

(3-3) GET 전송 - 저장(사용하면 안됨)

• 요청할 메시지를 post에서 get 바꾸면 웹브라우저가 생성하는 요청 HTTP 메시지가 데이터형식을 쿼리 파라미터로 변경하여 생성함
• 당연히 리소스를 변경하는 곳에서는 GET으로 사용하면 절대 안됨

(3-4) GET 전송 - 조회

• 조회기능은 GET으로 가능

(3-5) multipart/form-data

• 멀티로 여러 컨텐츠 타입에 대한 데이터(바이너리데이터)를 전송할 때 사용(파일 같은 것)

 

(3-6)HTML Form 데이터 전송 - 정리

• HTML Form submit시 POST 전송: 회원가입, 상품 주문, 데이터 변경
• Content-Type : application/x-www-form-urlencoded (디폴트)
  
  • form의 내용을 메시지 바디를 통해서 전송(key=value, 쿼리파라미터형식)
  • 전송 데이터를 url encoding 처리함 (abc김 -> abc%EA%B9%80 / UTF-8 형식을 URL인코딩)
• HTML Form은 GET전송도 가능
• Content-Type: multypart/form-data
  
  • 파일 업로드 같은 바이너리 데이터 전송시 사용
  • 다른 종류의 여러 파일과 폼의 내용을 함께 전송(multipart)
• HTML Form 전송은 GET,POST만 지원
• 디테일한 내용은 검색!

(4) HTTP API 데이터 전송

• 전송할 데이터를 직접 다 만들어서 전송(라이브러리들이 있음)
• 서버 to 서버 : 백엔드 시스템 통신
• 앱 클라이언트 : 아이폰, 안드로이드 등
• 웹 클라이언트 : 자바스크립트를 통한 통신에 사용(AJAX), React, Vue JS 같은 웹 클라이언트와 API 통신
• POST, PUT, PATCH : 메시지 바디를 통해 데이터 전송
• GET : 조회할 때 사용, 쿼리 파라미터로 데이터 전달
• Content-Type : application/json(사실상 표준), 과거에는 XML을 가 주를 이루었으나 현재는 JSON을 주로 사용

---

5. HTTP 메서드 활용 - HTTP API 설계 예시

1) HTTP API 설계 예시

(1) HTTP API - 컬렉션

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

(2) HTTP API - 스토어

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

(3) HTML FORM 사용

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

2) 회원관리 시스템 - API설계

(1-1) POST 기반 등록

• 회원 목록 /members -> GET
• 회원 등록 /members -> POST
• 회원 조회 /members/{id} -> GET
• 회원 수정 /members/{id} -> PATCH(부분수정 - 가장 좋음), PUT(완전수정 - 게시판의 글을 수정 등), POST(애매할 때)
• 회원 삭제 /members/{id} -> DELETE

(1-2) POST - 신규 자원 등록 특징

요청 메시지 (클라이언트 -> 서버)	응답 메시지 (서버 -> 클라이언트)
클라이언트가 등록될 리소스의 URI를 모름	서버가 새로 등록된 리소스 URI가 생성
POST /members	HTTP/1.1 201 Created Location: /members/100
컬렉션(Collection) 형식
서버가 관리하는 리소스 디렉토리, 서버가 리소스의 URI를 생성하고 관리 위 메시지에서의 컬렉션 리소스 : /members

 

(2-1) PUT 기반 등록

• 파일 목록 /files -> GET
• 파일 조회 /files/{filename} -> GET
• 파일 등록 /files/{filename} -> PUT(업로드할 파일을 기존 파일에 덮어씌우거나 없으면 새로생성)
• 파일 삭제 /files/{filename} -> DELETE
• 파일 대량 등록 /files -> POST

(2-2) PUT - 신규 자원 등록 특징

요청 메시지 (클라이언트 -> 서버)

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

PUT /files/star.jpg

스토어(store) 형식

클라이언트가 관리하는 리소스 저장소와 리소스의 URI를 알고 관리함 위 메시지에서의 스토어 : /files

 

** 참고

• 대부분 실무에서는 POST기반의 컬렉션을 사용하고 PUT은 거의 없음

3) HTML FORM 사용

• GET, POST만 지원하므로 제약이 있음
• AJAX같은 기술을 사용해서 해결 가능(HTTP API 전송)

(1) 회원관리 시스템 - HTML FORM 사용

• 회원 목록 /members -> GET
• 회원 등록 폼 /members/new -> GET
• 회원 등록 /members/new(컨트롤 URI), /members -> POST(변수 경우를 대비하여 경로를 맞추는 것을 권장, 개인차이가 있음)
• 회원 조회 /members/{id} -> GET
• 회원 수정 폼/members/{id}/edit -> GET
• 회원 수정 /members/{id}/edit(컨트롤 URI), /members/{id} -> POST
• 회원 삭제 /members/{id}/delete(컨트롤 URI) -> POST

(2) HTML FORM - 신규 자원 등록 특징

• GET, POST만 지원하므로 제약이 있으나 컨트롤 URI 활용하여 해결가능함
• HTTP메서드로 해결하기 애매한 경우에 사용(HTTP API인 경우도 포함)
• POST의 /new, /edit, /delete가 컨트롤 URI

(3) 컨트롤 URI

• 이상적으로는 HTTP 메소드로 다 해결하면 좋겠지만 실무의 상황은 더 복잡하므로 컨트롤 URI를 매우 많이 씀
• 너무 남발하기보다는 기본적으로 HTTP메서드로 해결을 해보고 안되면 사용하는 것을 권장하고 보통 동사로 된 리소스 경로를 사용

4) 정리

(1) HTTP API - 컬렉션

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

(2) HTTP API - 스토어

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

(3) HTML FORM 사용

• 순수 HTML + HTML form 사용
• GET, POST만 지원

(4-1) 참고하면 좋은 URI 설계 개념 (정답은 아니지만 좋은 예)

• https://restfulapi.net/resource-naming

(4-2) 문서(document)

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

(4-3) 컬렉션(collection)

• 서버가 관리하는 리소스 디렉터리
• 서버가 리소스의 URI를 생성하고 관리
• 예) /members

(4-4) 스토어(store)

• 클라이언트가 관리하는 자원 저장소
• 클라이언트가 리소스의 URI를 알고 관리
• 예) /files

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

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