배움을 기록으로

5. HTTP 메서드 활용

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

'데이터 전달 방식은 크게 2가지!'

• 쿼리 파라미터를 통한 데이터 전송
  • GET
  • 주로 정렬 필터(검색어)
• 메시지 바디를 통한 데이터 전송
  • POST, PUT, PATCH
  • 회원가입, 상품주문, 리소스 등록, 리소스 변경

'데이터 전송 케이스는 크게 4가지!'

• 정적 데이터 조회
  • 이미지, 정적 텍스트 문서
  • GET 메서드 사용
  • 쿼리 파라미터 없이 리소스 경로로 단순하게 조회
    
    
• 동적 데이터 조회
  • 주로 검색, 게시판 목록에서 정렬 필터(검색어)
  • 조회 조건을 줄여주는 필터, 조회 결과를 정렬하는 조건에 주로 사용
  • GET 메서드 사용
  • GET은 쿼리 파라미터를 사용하여 데이터 전달
  • 예) https://www.google.com/search?q=인프런
    
    
• HTML, Form을 통한 데이터 전송
  • HTML Form submit시 POST 전송
    • 예) 회원가입, 상품주문, 데이터 변경
  • Content-Type: application/x-www-urlencoded 사용
    • form의 내용을 메시지 바디를 통해서 전송 (key=value, 쿼리 파라미터 형식)
    • 전송 데이터를 urlencoding 처리 (서버에서 decoding이 필요할 수 있음)
      • 예) abc김 -> abs%EA%B9*80 
  • HTML Form은 GET 전송도 가능
  • Content-Type: multipart/form-data
    • 파일 업로드 같은 바이너리 데이터 전송시 사용
    • 다른 종류의 여러 파일과 폼의 내용 함께 전송 가능 (그래서 이름이 multipart)
  • 참고: HTML Form 전송은 GET, POST만 지원
    
    
• HTTP API를 통한 데이터 전송
  • 예) 회원가입, 상품주문, 데이터 변경
  • 서버 to 서버
    • 백엔드 시스템 통신
  • 앱 클라이언트
    • 아이폰, 안드로이드
  • 웹 클라이언트(Ajax)
    • HTML에서 Form 전송 대신 자바 스크립트를 통한 통신에 사용 (AJAX)
    • 예) React, VueJs 같은 웹 클라이언트와 API 통신
  • POST, PUT, PATCH: 메시지 바디를 통해 데이터 전송
  • GET: 조회, 쿼리 파라미터로 데이터 전달
  • Content-Type: application/json을 주로 사용 (사실상 표준)
    • TEXT, XML, JSON 등등

5.2. HTTP API 설계 예시

'POST 기반 등록'

• 클라이언트는 등록될 리소스의 URI를 모른다.
  • 회원등록 /members -> POST
  • POST /members
• 서버가 새로 등록된 리소스 URI를 생성해준다.
  • HTTP/1.1 201 Created
    Location: /members/100
  • 예) 회원등록시, 회원번호는 API단에서 생성한다.
         (고객이 가입정보에 회원번호를 입력하지 않는다)
• 컬렉션 (Collection)
  • 서버가 관리하는 리소스 디렉토리
  • 서버가 리소스의 URI를 생성하고 관리
  • 여기서 컬렉션은 /members

[ 예시 ]

• 회원 목록 /members -> GET
• 회원 등록 /members -> POST
• 회원 조회 /members/{id} -> GET
• 회원 수정 /members/{id} -> PATCH, PUT, POST
  • 보통은 PATCH를 사용하는 것을 추천 (수정하려는 데이터만 넘겨서 수정 가능)
  • PUT은 완전히 덮어써도 괜찮은 경우
    • 예) 게시판의 게시글을 수정하는 경우
• 회원 삭제 /members/{id} -> DELETE

'PUT 기반 등록'

• 클라이언트가 리소스 URI를 알고 있어야 한다.
  • 파일 등록 /files/{filename} -> PUT
  • PUT /files/start.jpg
  • 예) 파일 등록 (클라이언트가 파일명을 알고있다)
• 클라이언트가 직접 리소스의 URI를 지정한다.
• 스토어 (Store)
  • 클라이언트가 관리하는 리소스 저장소
  • 클라이언트가 리소스의 URI를 알고 관리
  • 여기서 스토어는 /files
  • 예) 정적 컨텐츠 관리, 원격 파일 관리

[ 예시 ]

• 파일 목록 /files-> GET
• 파일 조회 /files/{filename} -> GET
• 파일 등록 /files/{filename} -> PUT
• 파일 삭제 /files/{filename} -> DELETE
• 파일 대량 등록 /files -> POST
  •  

'HTML FORM 사용'

• 순수 HTML + HTML form 사용
• HTML FORM은 GET, POST만 지원
• 컨트롤러(controller), 컨트롤 URI
  • GET, POST만 지원하므로 제약이 있음
  • 이런 제약을 해결하기 위해 동사로 된 리소스 경로 사용
  • POST의 /new, /edit, /delete가 컨트롤 URI
  • HTTP 메서드로 해결하기 애매한 경우 사용 (HTTP API 포함)
    

[ 예시 ]

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

References

https://www.inflearn.com/course/http-%EC%9B%B9-%EB%84%A4%ED%8A%B8%EC%9B%8C%ED%81%AC

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

4. HTTP 메서드

4.1. HTTP API를 만들어보자

'회원 정보 관리 API의 URI를 설계해보자'

• 회원 목록 조회 /read-member-list
• 회원 조회 /read-member-by-id
• 회원 등록 / create-member
• 회원 수정 /update-member
• 회원 삭제 /delete-member
  
  
  

'이것은 좋은 URI 설계일까?'

• URI 설계시 가장 중요한 것은 리소스 식별이다
• 리소스의 의미는 뭘까?
  • 회원을 등록하고 수정하고 조회하는게 리소스가 아니다!
  • 예) 미네랄을 캐라 -> 미네랄이 리소스
  • 회원이라는 개념 자체가 바로 리소스다.
• 리소스는 어떻게 식별하는게 좋을까?
  • 회원을 등록하고 수정하고 조회하는 것을 모두 배제
  • 회원이라는 리소스만 식별하면 된다. -> 회원 리소스를 URI에 매핑
• URI 계층 구조를 활용한다.
  • 슬래시 구분자(/)는 계층 관계를 나타내는데 사용한다.
  • 예) http://test.example.com/members/{id}

'리소스 식별, URI 계층 구조를 활용하여 URI 설계를 다시 해보자!'

• 회원 목록 조회 /members
• 회원 조회 /members/{id}
• 회원 등록 /members/{id}
• 회원 수정 /members/{id}
• 회원 삭제 /members/{id}
  
• 참고: 계층 구조상 상위를 컬렉션으로 보고 복수 단어 사용 권장(member -> members)
  
  
  
  

'같은 리소스를 사용하는 경우, 어떻게 구분해야 할까?'

• 리소스와 해당 리소스를 대상으로 하는 행위를 분리
  • 리소스: 회원
  • 행위: 조회, 등록, 삭제, 변경
• 리소스는 명사, 행위는 동사 (미네랄을 캐라)
• 행위(메서드)는 HTTP 메서드로 구분한다.

[ HTTP 메서드 ]

• GET: 리소스 조회
  • 서버에 전달하고 싶은 데이터는 query(쿼리 파라미터, 쿼리 스트링)를 통해서 전달
  • 메시지 바디를 사용해서 데이터를 전달할 수 있지만, 지원하지 않는 곳이 많아서 권장하지 않음
• POST: 요청 데이터 처리, 주로 등록에 사용
  • 메시지 바디를 통해 서버로 요청 데이터 전달
  • 주로 전달된 데이터로 신규 리소스 등록, 프로세스 처리에 사용
  • 애매한 곳은 POST를 사용하면 된다 (다른 메서드로 처리하기 애매한 경우)
• PUT: 리소스를 대체, 해당 리소스가 없으면 생성
  • POST와 차이점: 클라이언트가 리소스 위치를 알고 URI 지정
    • 예) /members/{id}
  • PUT은 기존 리소스를 삭제하고 완전히 대체하기 때문에 중요한 데이터는 PUT을 사용하면 안된다.
    (중요한 데이터를 부분 수정하려면 PATCH를 사용한다)
• PATCH: 리소스 부분 변경
• DELETE: 리소스 삭제
  
  

[ HTTP 메서드 속성 ]

• 안전 (Safe Methods)
  • 호출해도 리소스를 변경하지 않는다.
  • GET, HEAD 메서드가 안전 메서드이다.
• 멱등 (Idenmpotent Methods)
  • 한 번 호출하든 두 번 호출하든 100번 호출하든 결과가 똑같다. (외부 요인으로 중간에 리소스가 변경되는 것은 고려 X)
  • 멱등 메서드
    • GET: 한 번 조회하든, 두 번 조회하든 같은 결과가 조회된다.
    • PUT: 결과를 대체한다. 따라서 같은 요청을 여러번 해도 최종 결과는 같다.
    • DELETE: 결과를 삭제한다. 같은 요청을 여러번 해도 삭제된 결과는 똑같다.
    • POST: 멱등이 아니다! 두 번 호출하면 같은 결제가 중복해서 발생할 수 있다.
      
    • PATCH: 멱등으로 설계할 수도 있지만, 멱등이 아니게 설계할 수도 있다. (참고)
      
  • 활용
    • 자동 복구 메커니즘
    • 서버가 TIMEOUT 등으로 정상 응답을 못주었을 때, 클라이언트가 같은 요청을 다시 해도 되는가? 판단 근거
      
• 캐시가능 (Cacheable Methods)
  
  • 응답 결과 리소스를 캐시해서 사용해도 되는가?
  • GET, HEAD, POST, PATCH 메서드가 캐시 가능
  • 실제로는 GET, HEAD 정도만 캐시로 사용
    • POST, PATCH는 본문 내용까지 캐시 키로 교려해야 하는데, 구현이 쉽지 않음
      
      

References

https://www.inflearn.com/course/http-%EC%9B%B9-%EB%84%A4%ED%8A%B8%EC%9B%8C%ED%81%AC