좋은 API설계는 리소스를 식별해야 한다.

리소스의 의미

회원 API를 예로들면 회원 전체-조회/등록/조회/수정/삭제 API가 있을 때 전체-조회/등록/조회/수정/삭제가 리소스가 아니다.
회원이 리소스라고 할 수 있다.

즉, 구체적인 행위 - Method가 아닌 “하나 또는 여러개의 식별할 수 있는 고유한 것”을 리소스 라고 할 수 있다.

1. URL 설계

  • URL은 리소스만 식별하도록 해야 한다.

다음과 같이 행위를 포함하는게 아닌

  • 회원 전체 조회: /members
  • 회원 등록: /create-member
  • 회원 조회: /read-member-by-id
  • 회원 수정: /update-member
  • 회원 삭제: /delete-member w 리소스만 표현하도록 작성해야 한다.
  • 회원 전체 조회: /members
  • 회원 등록: /members/{id}
  • 회원 조회: /members/{id}
  • 회원 수정: /members/{id}
  • 회원 삭제: /members/{id}

하지만 URL만으로 API를 구분할 수 없다. 이를 HTTP method가 해결한다.

2. HTTP Method

주요 HTTP Method

  • GET: 리소스 조회
  • POST: 요청 데이터 처리

    주로 등록에 사용한다.

  • PUT: 리소스를 대체한다.

    해당 리소스가 없으면 생성

  • PATCH: 리소스 부분 변경
  • DELETE: 리소스 삭제

기타 HTTP Method

  • HEAD: GET과 동일하지만, 상태줄과 헤더만 반환한다.
  • OPTIONS: 대상 리소스에 대한 통신 가능 옵션(메서드)를 설명한다.

    주로 CORS에서 사용된다.

  • CONNECT: 대상 자원으로 식별되는 서버에 대한 터널을 설정한다.
  • TRACE: 대상 리소스에 대한 경로를 따라 메시지 루프백 테스트를 수행한다.

2-1. GET

리소스를 조회한다.

  • 서버에게 전달하고 싶은 데이터는 query를 통해 전달한다.

    ex. GET /board?page=1&count=10

  • Request Body를 사용할 수 있지만, 지원하는 곳이 적어 권장하지 않는다.

2-2. POST

요청 데이터를 처리한다.

  • 메시지 바디를 통해 서버로 요청 데이터를 전달한다.
  • 서버는 요청 데이터를 처리한다.

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

  • 주로 전달된 데이터로 신규 리소스 등록, 프로세스 처리에 사용된다.

그럼 POST는 도대체 어쩔 때 사용하는건데?

POST 메서드는 대상 리소스가 리소스의 고유 한 의미 체계에 따라 요청에 포함 된 표현을 처리하도록 요청한다.

  • 새 리소스 생성(등록)

    서버가 아직 식별하지 않은 새 리소스 생성 ex. 회원가입

  • 요청 데이터 처리

    단순히 데이터를 생성하거나, 변경하는 것을 넘어서 프로세스를 처리해야 하는 경우

    • 주문과 같이 “결제완료 → 배달시작 → 배달완료” 처럼 단순히 값 변경을 넘어 프로세스의 상태가 변경되는 경우
    • 예시) POST /orders/{orderId}/start-delivery와 같은 컨트롤 URI를 사용한다.
  • 다른 메서드로 처리하기 애매한 경우

    JSON으로 조회 데이터를 넘겨야 할 때, 혹은 회원 탈퇴같이 body에 JSON을 넘겨야 하는 경우

POST는 리소스를 생성할 때 만 사용하는 게 아니라 다양한 상황에서 사용된다. 서버에서 큰 변화가 일어나거나 다른 메서드로 처리하기 애매할 경우에도 사용한다.

URI설계에서 컨트롤 URI처럼 어쩔 수 없이 동사를 사용해야 하는 경우를 제외하고 모두 리소스를 식별할 용도로 사용하는게 좋다.

2-3. PUT

리소스를 대체한다.

  • 리소스가 있나? == true ? 대체 : 생성

    덮어버린다고 생각하면 된다.

  • 클라이언트가 리소스의 정확한 위치를 식별하고 있다.

PUT은 리소스를 덮어버리기 때문에 해당 리소스를 부분 수정하고 싶으면 PETCH를 사용해야 한다.

2-4. PETCH

리소스를 부분 변경한다.

2-5. DELETE

리소스를 제거한다.

3. HTTP method의 속성

3-1. 안전 - Safe

  • 호출해도 리소스를 변경하지 않는다.

    GET, HEAD

3-2. 멱등 - Idempotent

f(f(x)) = f(x)

  • 한 번 호출하든, 두 번 조회하든 같은 결과가 조회된다.

1. 멱등 메서드

  • GET

    여러번 조회해도 같은 결과를 조회한다.

  • PUT

    결과를 대체하므로 같은 요청을 여러번 호출해도 최종 결과가 같다.

  • DELETE

    결과를 삭제하므로 같은 요청을 여러번 수행해도 삭제된 결과는 같다.

2. 멱등하지 않는 메서드

  • POST

    여러번 호출하면 계속적으로 데이터가 추가되므로 멱등하지 않다.

3. 멱등성의 활용

  • 자동 복구 메커니즘
  • 서버가 TIME OUT 등으로 정상 응답을 주지 않았을 떄, 클라이언트가 같은 요청을 해도 되는지에 대한 판단 근거가 된다.

4. 멱등성의 주의점

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

  • 사용자1 : GET -> {username : A, age : 20}
  • 사용자2 : PUT -> {username : A, age : 30}
  • 사용자1 : GET -> {username : A, age : 30} → 사용자2의 영향으로 데이터(age)가 변경됨

3-3. 캐시 가능 - Cacheable

  • GET, HEAD, POST, PATCH 캐시 가능

    실제로는 GET, HEAD 매서드만 캐시를 사용한다.

Reference

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