- HTTP API
- HTTP 메서드 - GET, POST
- HTTP 메서드 - PUT, PATCH, DELETE
- HTTP 메서드의 속성
🌐 HTTP API
🗃️어떤것이 좋은 api설계일까?
만약 위와같은 요구사항이 있다고 가정하자.
요구사항
회원 정보 관리 API를 만들어라.
• 회원 목록 조회
• 회원 조회
• 회원 등록
• 회원 수정
• 회원 삭제
URI를 이름에 맞춰서 설계한다.
API URI 설계
• 회원 목록 조회 /read-member-list
• 회원 조회 /read-member-by-id
• 회원 등록 /create-member
• 회원 수정 /update-member
• 회원 삭제 /delete-member
🗃️ 가장 중요한것은 리소스 식별이 잘 되야 좋은설계이다.
API URI고민
"리소스의 의미"
회원을 조회하다 -> 리소스가 아님
"회원" -> 자체가 리소스임.
• 회원 목록 조회
• 회원 조회
• 회원 등록
• 회원 수정
• 회원 삭제
↓리소스 식별, URI 계층 구조 활용
• 회원 목록 조회 /members
• 회원 조회 /members/{id}
• 회원 등록 /members/{id}
• 회원 수정 /members/{id}
• 회원 삭제 /members/{id}
• 참고: 계층 구조상 상위를 컬렉션으로 보고 복수단어 사용 권장(member -> members)
↓• 회원 목록 조회 /members
• 회원 조회 /members/{id} -> 어떻게 구분하지?
• 회원 등록 /members/{id} -> 어떻게 구분하지?
• 회원 수정 /members/{id} -> 어떻게 구분하지?
• 회원 삭제 /members/{id} -> 어떻게 구분하지?
🗃️ 리소스를 어떻게 식별하는게 좋을까?
회원을 등록,조회,수정하는것은 모두 배제
회원이라는 리소스만 식별하면된다.
리소스와 행위를 분리한다.
리소스는 명사, 행위는 동사가 된다.
행위(메서드)는 어떻게 구분하지?
🌐 HTTP 메서드 - GET, POST
클라이언트가 서버에 요청을할때 기대하는 행동.
- GET - 리소스 조회
- POST - 데이터를줄테니 처리해달라는것.
- PUT - 리소스를 대체, 리소스가 없으면 생성
- PATCH - 리소스를 부분적으로 변경
- DELETE - 리소스 삭제
요새는 리소스말고 리프레젠테이션이라는 표현을 쓴다.
- HEAD: GET과 동일하지만 메시지 부분을 제외하고, 상태 줄과 헤더만 반환
- OPTIONS: 대상 리소스에 대한 통신 가능 옵션(메서드)을 설명(주로 CORS에서 사용)
//이 둘은 거의 안씀.
- CONNECT: 대상 리소스로 식별되는 서버에 대한 터널을 설정
- TRACE: 대상 리소스에 대한 경로를 따라 메시지 루프백 테스트를 수행
🌐 GET
/100번의 유저 정보를 주세요!
서버에서 답을 보냅니다.
HTTP/1.1버전, 200 OK(오류없이 ok라는뜻)
타입은 application/json
length 길이는 34
🌐 POST
신규 등록, 변경에 쓰인다.
username "young"이고 age"20"인 메세지를 /members에 전달한다.
전달받은 메세지는 /100 (신규리소스)가 생성된다.
등록이 완료 된 경우엔 201 Created를 보낸다. (200도 가능)
201번을 보내는 경우는 Location(등록된 신규 리소스)를 적어준다.
🗃️ 요청 데이터를 어떻게 처리한다는 뜻일까?
-
스펙: POST 메서드는 대상 리소스가 리소스의 고유 한 의미 체계에 따라 요청에 포함 된 표현을 처리하도록 요청합니다. (구글 번역)
-
HTML 양식에 입력 된 필드와 같은 데이터 블록을 데이터 처리 프로세스에 제공
예) HTML FORM에 입력한 정보로 회원 가입, 주문 등에서 사용 -
게시판, 뉴스 그룹, 메일링 리스트, 블로그 또는 유사한 기사 그룹에 메시지 게시
예) 게시판 글쓰기, 댓글 달기 -
서버가 아직 식별하지 않은 새 리소스 생성
예) 신규 주문 생성 -
기존 자원에 데이터 추가
예) 한 문서 끝에 내용 추가하기 -
정리: 이 리소스 URI에 POST 요청이 오면 요청 데이터를 어떻게 처리할지 리소스마다 따로 정해야 함 -> 정해진 것이 없음
🗃️ POST 정리
- 새 리소스 생성(등록)
서버가 아직 식별하지 않은 새 리소스 생성
- 새 리소스 생성(등록)
- 요청 데이터 처리**
단순히 데이터를 생성하거나, 변경하는 것을 넘어서 프로세스를 처리해야 하는 경우
예) 주문에서 결제완료 -> 배달시작 -> 배달완료 처럼 단순히 값 변경을 넘어 프로세스의 상태가 변경되는 경우
- 요청 데이터 처리**
- POST의 결과로 새로운 리소스가 생성되지 않을 수도 있음
-예) POST /orders/{orderId}/start-delivery (컨트롤 URI) - 다른 메서드로 처리하기 애매한 경우
예) JSON으로 조회 데이터를 넘겨야 하는데, GET 메서드를 사용하기 어려운 경우
애매하면 POST!
- 다른 메서드로 처리하기 애매한 경우
🌐 PUT
post와 put의 차이점은 클라이언트가 리소스의 위치를 알고, uri를 지정한다는 뜻이다.
리소스를 대체할때, 완전히 대체함으로 기존 리소스를 없애버리고 완전히 날려버림. "완전히 대체함."
username 필드가 없는데 age만 "50"으로 바꾸면 어떻게 될까?
username필드가 완전히 삭제되며, put으로 보낸 리소스를 담은 age "50" 으로 덮어씌워지게된다.
리소스를 완전히 대체하게된다.
* 부분만 변경하려면 PATCH를 사용한다.
🌐 PATCH
username 필드가 없는 경우에 age만 변경하려고한다.
PATCH를 이용하면 기존리소스에 추가로 age만 변경된다.
🌐 DELETE
- 리소스 제거.
members/100을 삭제한다.
🌐 HTTP 메서드의 속성
• 안전(Safe Methods)
• 멱등(Idempotent Methods)
• 캐시가능(Cacheable Methods)
🗃️ 안전(Safe)
변경해도 변경이 일어나지않는걸 안전하다고 한다.
GET, HEAD 외에는 모두 안전하지 않음.
- Q: 그래도 계속 호출해서, 로그 같은게 쌓여서 장애가 발생하면요?
->> A: 안전은 해당 리소스만 고려한다. 그런 부분까지 고려하지 않는다.
🗃️ 멱등(Idempotent)
- 한 번 호출하든 두 번 호출하든 100번 호출하든 결과가 똑같다
*** 멱등 메서드
• GET: 한 번 조회하든, 두 번 조회하든 같은 결과가 조회된다.
• PUT: 결과를 대체한다. 따라서 같은 요청을 여러번 해도 최종 결과는 같다.
• DELETE: 결과를 삭제한다. 같은 요청을 여러번 해도 삭제된 결과는 똑같다.
• POST: 멱등이 아니다! 두 번 호출하면 같은 결제가 중복해서 발생할 수 있다.
*** 멱등의 활용
• 자동 복구 메커니즘
(여러번 요청해서 복구)
• 서버가 TIMEOUT 등으로 정상 응답을 못주었을 때, 클라이언트가 같은 요청을 다시 해도 되는가?의 판단, 근거
Q: 재요청 중간에 다른 곳에서 리소스를 변경해버리면?
• 사용자1: GET -> username:A, age:20
• 사용자2: PUT -> username:A, age:30
• 사용자1: GET -> username:A, age:30 -> 사용자2의 영향으로 바뀐 데이터 조회
• A: 멱등은 외부 요인으로 중간에 리소스가 변경되는 것 까지는 고려하지는 않는다.
🗃️ 캐시가능 Cacheable
- 응답 결과 리소스를 캐시해서 사용해도 되는가?
- GET, HEAD, POST, PATCH 캐시가능
- 실제로는 GET, HEAD 정도만 캐시로 사용
(실무에서는 GET만 캐시로 사용) - POST, PATCH는 본문 내용까지 캐시 키로 고려해야 하는데, 구현이 쉽지 않음
