4. HTTP API 메서드

HTTP API 메서드

요구사항

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

 

일반적으로 이렇게 생각할 수 있다.

 

API URL 설계

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

하지만, 이는 좋은 설계가 아니다. URI에서 가장 중요한 것은 리소스 식별이다.

리소스에 대해 알아보자.

 

리소스란?

회원을 등록,수정,조회 하는것은 리소스가 아니다. 리소스는 “회원” 그 자체가 리소스이다.

계층 구조 상위를 컬렉션으로 보고 복수 단어를 사용하는 것이 좋다. ex) members

• 회원 목록 조회 → /members
• 회원 조회 → /members/{id}
• 회원 등록 → /members/{id}
• 회원 수정 → /members/{id}
• 회원 삭제 → /members/{id}

어? 조회,등록,수정,삭제 URI가 모두 같은데 구분을 어떻게 해?

다시한번 말하지만 URI는 리소스만 식별한다.

우리는 리소스와 행위를 분리해야한다.

• 리소스: 회원 - 명사 (N)
• 행위: 조회, 등록, 삭제, 변경 - 동사 (V)

자 이제 각각의 행위끼리 구분해 보자.

HTTP 메서드

• GET: 리소스 조회
• POST: 요청 데이터 처리, 주로 등록에 사용한다.
• PUT: 리소스를 대체하며, 해당 리소스가 없을 경우 생성한다.
• PATCH: 리소스 부분 변경
• DELETE: 리소스 삭제

 

---

1. GET

리소스 조회에 사용하며, 서버에 전달하고 싶은 데이터( ex) 검색엔진에 넘길 데이터)는 쿼리(쿼리 파라미터, 쿼리 스트링)을 통해 전달한다.

메세지 바디로 데이터를 전달 할 수는 있지만, 권장하지 않는다.

 

(1) 메시지 전달 - 클라이언트가 100번 유저를 요청한다.

(2) 서버도착 - 서버에 GET 메시지 도착

(3) 응답데이터 - 서버에서 해당 데이터를 가지고 응답 메시지를 만들어 클라이언트에 보낸다.

ex) HTTP/version 200 OK Content-Type: 타입명, Content-Length: 길이

 

---

2. POST

클라이언트에서 서버로 요청 보낼때, 정보를 준다. 메시지 바디를 통해 서버로 요청 데이터를 전달한다.

서버에서는 요청 데이터를 처리한다. 메시지 바디를 통해 들어온 데이터를 처리하는 모든 기능을 수행한다.

 

(1) 메시지 전달 - POST 방식으로 데이터를 담아 보낸다.

미리 약속을 해놓는다.

ex) 서버입장에서 클라이언트로부터 /members로 요청이 오면 그 데이터를 내부적으로 신규등록하기로 약속한다.

(2) 신규 리소스 생성 - 서버는 POST로 신규 등록하는 요청이란 걸 알고 처리한다.

ex) 100번이라는 신규 리소스 식별자가 생성됨.

(3) 응답 데이터 - 신규 자원 생성은 200,201로 응답하고, 자원이 생성된 경로와 데이터도 함께 보낼 수 있다.

201의 경우 Location: /members/100으로 위치도 알려준다.

POST는 요청 데이터를 어떻게 처리할까?

POST는 요청에 들어있는 표현을 처리하는 요청 메소드다. 아래와 같은 기능에 이용된다.

 

• HTML 양식에 입력된 데이터 블록을 데이터 처리 프로세스에 제공한다.

ex)HTML 폼에 입력한 정보로 회원 가입, 주문

 

• 게시판, 뉴스, 블로그 그룹에 메시지를 게시한다.

ex) 게시판 글쓰기, 댓글쓰기

 

• 새 리소스 생성

ex) 신규 주문 생성

 

• 기존 자원에 데이터 추가

ex) 문서 끝에 내용 추가

 

리소스 URI에 POST요청이 들어오면 정해진것이 없기에 어떻게 처리할지 리소스마다 정해줘야 한다.

 

정리해보면,

1)서버가 아직 식별하지 않은 새 리소스를 생성, 등록하고,

2)요청 데이터를 처리한다.

 

• 단순 데이터 생성,변경이 아닌 프로세스를 처리해야 하는경우

ex) 주문 → 결제 완료 → 배달 시작 → 배달 완료 같은 프로세스 상태를 변경하는 것

 

• 새로운 리소스가 생성되지 않을 수 있다.

ex)POST /orders/{orderId}/start-delivery

 

위에서 리소스 단위로 해서 만들자고 했는데, 부족하다면 이렇게라도 해야한다.

• 다른 메서드로 처리하기 애매한 경우

애매한경우 POST를 쓰면 된다. 단, 조회의 경우 GET을 사용하면 캐싱을 할 수 있기에 GET을 쓰는 추세이다.

 

---

3. PUT = 덮어쓰기

• 리소스를 대체한다. 완.전.히

/members에 100번이라는 리소스가 있다면? 리소스를 대체한다.

/members에 100번이라는 리소스가 없다면? 리소스를 생성한다.

 

• 클라이언트가 리소스를 식별한다.

애매하면 POST 쓰라며, 그럼 PUT도 필요없는거 아닌가?

PUT의 경우 POST와 달리 클라이언트가 리소스 위치를 알고 URI를 지정한다.

클라이언트가 /mebers/100번에 넣는것

요게 POST였다. /members 에다가 넣으면 클라이언트는 리소스가 100번에 만들어질지, 101번에 만들어질지 모른다.

 

(1) 100번 유저에게 리소스를 보내겟다고 요청보낸다.

(2-1) 이때, 기존의 데이터가 있다면 완전히 대체된다.

(2-2) 이때, 기존의 데이터가 없다면 신규로 생성한다.

(3-1) 만약 부분 요청을 보낸다면

(3-2) 새로운 데이터로 기존 데이터를 완전히 대체한다.

그렇기에 PUT은 수정 보다는 갈아끼운다. 라는 표현이 더 적절하다.

난 수정하고 싶은데?

 

---

4. PATCH

(1-1) 리소스 부분 변경

(1-2) 부분적으로 데이터를 보내도, 그 데이터만 변경된다.

 

---

5. DELETE

리소스 제거 - 나 100번 지울래

결론은? POST는 무적이다.

 

---

HTTP 메서드의 속성

 

1. 안전 - 호출해도 리소스를 변경하지 않는 성질

변경이 일어나면 안전하지 않은 것

 

GET은 단순 조회만 하기 때문에 안전하다. POST, DELETE, PATCH, PUT은 당연히 안전하지 않다.

GET이 안전하다고 해도 계속 호출해서 수 많은 로그를 쌓다가 서버가 터져버린다면?

→ 안전은 해당 리소스가 변하는지만 고려한다. 그 부분까지 고려하지 않는다.

 

2. 멱등 - 한 번 호출하든, 두 번 호출하든, 100번 호출하든 결과가 동일한 것

• GET: 한번호출하든~ 결과가 똑같다.
• PUT: 똑같은 파일에 똑같은 요청을 하면 기존 것을 날리고 새로운 것을 덮기 때문에 항상 같다.
• DELETE: 삭제하면 지워짐. 같은 요청을 여러 번 해도 최정 결과는 같다.
• POST: 멱등 아니다. 예를들어 결제시스템을 두번 호출하면 중복 결제이다.

 

멱등 활용

• 자동 복구 메커니즘

ex) DELETE 호출했는데 서버에서 응답이 없어서, 다시 클라이언트가 재시도 한다. 왜 ? 멱등하니까

 

• 서버가 TIMEOUT 등으로 정상 응답을 주지 못했을 때, 클라이언트가 같은 요청을 해도 되는지에 대한 판단 근거가 된다.

그런데 재요청 중간에 다른 곳에서 리소스를 변경해버리면? 이러면 멱등이 아닌것 아닌가?

 

• 사용자 1: GET username: A, age: 20
• 사용자 2: PUT username: A, age: 30
• 사용자 1: GET username: A, age:30

 

바뀐데이터를 조회하게 된다.

멱등은 외부 요인으로 중간에 리소스가 변경되는 것 까지는 고려하지 않는다.

 

3. 캐시가능 - 응답 결과로 온 리소스를 캐시에 저장해서 사용해도 되나?

캐시를 사용하려면 원본 리소스와 키가 맞아야함. POST와 PATCH는 본문 내용까지 고려하기가 복잡하지만,

GET은 url만 키로 잡고 캐싱하면 되기에 심플하다.

실무에서는 GET만 캐시로 사용한다.