HTTP 메서드

HTTP API 만들기

• 회원 정보 관리 API
  • 회원 목록 조회 /members GET
  • 회원 조회 /members/{id} POST
  • 회원 등록 /members POST
  • 회원 수정 /members/{id} PATCH, PUT, POST
    • PUT은 덮는 것이기 때문에 데이터를 전부 다 보내야한다는 단점
    • PATCH를 쓰는 것이 가장 좋음 (부분 수정)
    • 애매하면 POST
  • 회원 삭제 /members/{id} DELETE

API URI 설계

• 가장 중요한 것은 리소스 식별
  • 회원을 등록, 조회하는 게 리소스가 아닌, 회원이란 개념 자체가 리소스
• 어떻게 식별하는게 좋을지?
  • 회원을 등록, 수정, 조회하는 것을 모두 배제한다.
  • 회원이라는 리소스만 식별 → 회원 리소스를 URI에 매핑
• 계층 구조상 상위를 컬렉션으로 보고 복수단어 사용을 권장한다.
• 리소스와 행위를 분리하기
  • 리소스는 명사, 행위는 동사
  • 행위(메서드)는 어떻게 구분하나? → HTTP 메서드를 사용해서!

GET

• 리소스 조회
• 서버에 전달하고픈 데이터는 query를 통해 전달
• 메시지 바디를 사용해 데이터를 전달할 수 있지만, 지원하지 않는 곳이 많다.

POST

• 요청 데이터 처리, 주로 등록, 프로세스 처리에 사용
• 메시지 바디를 통해 서버로 요청 데이터 전달
• 서버는 요청 데이터를 처리한다.
• 대상 리소스가 리소스의 고유한 의미 체계에 따라 요청에 포함된 표현을 처리하도록 요청
  • HTML 양식에 입력된 필드와 같은 데이터 블록을 처리 프로세스에 제공
    • 회원가입, 주문
  • 게시판, 뉴스 그룹, 블로그 메시지 게시
    • 게시판 글, 댓글 작성
  • 서버가 아직 식별하지 않은 새 리소스 생성하기
    • 신규 주문 생성
  • 기존 자원에 데이터 추가
    • 한 문서 끝에 내용 추가
  • 프로세스 처리
    • 주문에서 결제완료 배달시작 배달완료 처럼 상태가 변경되는 것
  • 다른 메서드로 처리하기 어려운 경우
    • JSON으로 조회 데이터를 넘겨야할 때 GET을 쓰기 어려우면 사용
• 어떻게 처리해야할지는 리소스마다 따로 정해놔야 한다.

PUT

• 리소스를 대체, 해당 리소스가 없으면 생성, 덮어버린다.
• 클라이언트가 리소스를 식별
  • 클라이언트가 리소스 위치를 알고 URI를 지정 (POST와의 차이)

PATCH

• 리소스 부분 변경

DELETE

• 리소스 삭제

기타 메서드

• HEAD: GET과 동일, 메시지 부분을 제외, 상태 줄과 헤더만 반환
• OPTIONS: 대상 리소스에 대한 통신 가능 옵션을 설명(CORS)
• CONNECT, TRACE

HTTP 메서드 속성

안전(Safe)

• 호출해도 리소스를 변경하지 않음
  • GET은 안전, POST 안전하지 않음
• 안전은 해당 리소스가 변하냐 변하지 않냐만 고려한다. 그 이후 과정은 고려하지 않는다.

멱등(Idempotent)

• 1번 호출, 2번 호출, 100번 호출...결과는 같은 것
• GET, PUT, DELETE
• POST는 멱등이 아니다.
• 왜 이런 개념이 필요한가?
  • 자동 복구 매커니즘 → 서버가 제대로 응답을 못주었을 때, 클라이언트가 다시 요청을 시도해도 되는지에 대한 판단 근거가 된다.
    • GET을 보내고 응답이 안왔을 때, GET은 멱등이기 때문에 다시 요청해도 되는 것!
• 외부 요인으로 인해 리소스가 변경되는 것은 고려하지 않는다.

캐시가능(Cacheable)

• 응답 결과 리소스를 캐시해서 사용해도 되는지?
• GET, HEAD, POST, PATCH 캐시가능
• 실제로는 GET, HEAD 정도만 캐시로 사용한다.
  • 이미지 같이 용량이 큰 것...

메서드는 어떻게 활용할까?

데이터 전송

• 쿼리 파라미터

  • GET
  • 검색어, 정렬 조건

• 메시지 바디

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

• 데이터 전송 상황들

  1. 정적 데이터 조회
     • 이미지, 정적 문서
     • 쿼리 파라미터 없이 리소스 경로로
  2. 동적 데이터 조회
     • 검색, 게시판 목록 정렬
     • 쿼리 파라미터 사용
     • GET 사용
  3. HTML Form
     • 회원가입, 주문, 데이터 변경
     • POST 사용
     • Content-Type: application/x-www-form-urlencoded 사용
       • 전송 데이터를 url encoding, 메시지 바디를 통해 key=value (쿼리 파라미터 형식)
     • Content-Type: multipart/form-data
       • 파일 전송시
  4. HTTP API
     • 회원가입, 주문, 데이터 변경
     • 서버 to 서버, 앱 클라이언트, Ajax
     • POST, PUT, PATCH, GET(조회용, 쿼리파라미터)
     • Content-Type: application/json을 주로 사용한다.

POST

• 클라이언트는 등록될 리소스의 URI을 모르고 서버에서 리소스 URI을 결정하고 만들어준다.
  • 예를 들면 회원 신규 등록을 할 경우, 회원 아이디를 넘겨줌 /members/10
• 위와 같은 형식을 컬렉션이라고 한다.
  • 서버가 관리하는 리소스 디렉토리, 서버가 리소스의 URI를 생성하고 관리
  • 컬렉션은 /members
• 대부분은 컬렉션 기반을 사용한다.

PUT

• 파일 관리 시스템
• 클라이언트가 새로 업로드할 파일 이름을 알고 있다. 없으면 새로 생성, 있으면 덮어버림
  • /files/{filename}
  • PUT을 사용하는 것이 적절하다.
• 위와 같은 형식은 스토어(Store)
  • 클라이언트가 리소스의 URI를 알고 관리
  • 스토어는 /files

HTML Form

• GET, POST만 지원
• AJAX 기술 활용할 수 있다.
  • 순수한 HTML은 GET, POST
• 사용 예
  • 회원 목록 /members GET
  • 회원 등록 폼 /members/new GET
  • 회원 등록 /members/new, POST
  • 회원 조회 /members/{id} GET
  • 회원 수정 폼 /members/{id}/edit GET
  • 회원 수정 /members/{id}/edit, POST
  • 회원 삭제 /members/{id}/delete POST

컨트롤 URI

• GET, POST만 지원하기에 제약이 있음, 제약을 해결하기 위해 동사로 된 리소스 경로 사용
• POST의 /new, /edit, /delete가 컨트롤 URI
• 최대한 HTTP 메서드로 해결하고 애매한 경우 사용하는 것

같이 보기

• https://restfulapi.net/resource-naming/
• 실제로 복잡해지면 설계가 어렵다.
  • 일단 컬렉션과 문서, HTTP 메서드로 해결한다. ("미네랄을 캐라" 이면 "캐라"를 제외하고 미네랄만 )
  • 그래도 안된다면 컨트롤 URI

reference

• inflearn-모든 개발자를 위한 HTTP 웹 기본 지식