HTTP API 를 만들어보자
회원 정보 관리 API를 만든다고 가정해보자. 회원 목록 조회, 회원 조회, 회원 등록, 회원 수정, 회원 삭제에 대한 API를 만들어야 한다.
그에 맞는 URI를 설계해야 하는데, 이 때 /create-member 이런 식으로 설계하면 좋은 설계는 아니다..!
왜?
리소스를 식별할 수 있도록 설계하는 것이 가장 좋은 방법!
리소스란?
회원을 등록하고 수정, 조회하는 행동이 리소스가 아니라 여기서는 회원 자체가 리소스인 것이다.
리소스를 어떻게 식별하는 게 좋을까?
회원이라는 리소스만 식별하면 되고, 회원 리소스를 URI에 매핑한다. 회원 조회를 /members/{id}로 했을 때, 회원 등록도 /members/{id} 이렇게 설정할 것이다. 그럼 이걸 어떻게 구분하는가..? → HTTP 메서드!!!
리소스와 행위를 분리하는 것이 중요
URI는 리소스(보통 명사)만 식별하고, HTTP 메서드는 행위(보통 동사)를 구분하게 한다.
ex) 리소스: 회원, 행위: 조회, 등록, 삭제, 변경
HTTP 메서드 - GET, POST
- GET: 리소스 조회
서버에 전달하고 싶은 데이터를 query(쿼리 파라미터, 쿼리 스트링)를 통해서 전달한다. 메세지 바디를 사용해서 데이터를 전달해도 되지만, 지원하지 않는 곳이 많아서 권장하진 않는다.
- POST: 요청 데이터 처리
HTTP 메서드 - PUT, PATCH, DELETE
- PUT: 리소스 대체
리소스가 있으면 기존 리소스를 대체하고, 리소스가 없으면 새로 생성한다. POST와 차이점은 클라이언트가 리소스 위치를 정확하게 알고 URI를 지정한다는 점이다.
만약
"age": 50을 보내면 기존 username 필드는 삭제되고, "age": 50로 대체된다.- PATCH: 리소스 부분 변경
PUT과 다르게 리소스의 일부분만 변경이 가능하다.
만약
"age": 50을 보내면 기존 username 필드는 유지되고, "username": "hello" , "age": 50로 변경된다.- DELETE: 리소스 제거
원하는 리소스의 위치를 지정하여 리소스를 제거할 수 있다.
HTTP 메서드의 속성
안전 (Safe Methods)
호출해도 리소스를 변경하지 않는다. GET은 단순히 조회만 하기 때문에 안전하다. 그런데 호출했을 때 리소스가 변경되는 것은 안전하다고 할 수 없다. 따라서, 리소스가 변경되지 않는 것을 안전하다고 한다.
안전은 해당 리소스만 고려한다는 것을 인지하자.
멱등 (Idempotent Methods)
몇 번 호출하든 리소스의 결과가 똑같은 것을 멱등하다고 한다. 멱등은 이럴 때 사용할 수 있다.
예를 들어, 서버가 타임아웃되어서 정상 응답을 하지 못했을 때, 클라이언트가 같은 요청을 다시해도 결과가 바뀌지 않는다면 같은 요청을 또 해도 된다는 의미이다.
같은 요청을 하기전에 다른 곳에서 리소스를 변경해버리더라도 상관없다. 멱등은 외부 요인으로 중간에 리소스가 변경되는 것까지는 고려하지 않기 때문이다.
- GET: 한 번 조회하든, 두 번 조회하든 같은 결과가 조회된다.
- PUT: 결과를 대체하기 때문에 같은 요청을 여러번해도 최종 결과는 같다.
- DELETE: 결과를 삭제하기 때문에 같은 요청을 여러번해도 삭제된 결과는 똑같다.
- POST: 멱등이 아니다. 두 번 호출하면 같은 결제가 중복해서 발생할 수 있다.
캐시가능 (Cacheable Methods)
응답 결과 리소스를 캐시해서 사용해도 되는가? 여기서 캐시해도 되냐는 의미는 웹 브라우저가 내부에 리소스를 저장해둔 것을 의미한다. 캐시 키를 일치하게 하여 캐시를 사용한다.
GET, HEAD, POST, PATCH가 캐시 가능하지만, 실제로는 GET, HEAD 정도만 캐시로 사용한다.
POST, PATCH는 메세지 바디까지 캐시 키로 고려해야 하는데 이를 구현하기는 쉽지 않기 때문이다.
GET, HEAD는 URI를 캐시 키로 잡고 캐시를 사용하면 된다.