REST 리소스의 단일 속성을 업데이트하기위한 API 디자인

Question

내가 작업중인 프로젝트의 스펙에서 알 수 있듯이 사용자 엔터티의 상태를 [VALID | NOT_VALID | TO_VALIDATE]. /사용자/: I 업데이트 할 때문에 USER_ID/상태

내 생각은 URL과 POST에 대한 새로운 하위 경로를 추가하는 것이 었습니다 USER_ID : 사용자를위한

현재 API는 /사용자 /이 경로를 당신이 가장 잘 찾을 수있는 선택을 디자인하는 단지 하나의 가치?

• 예를 들어, 쿼리 문자열을 사용하여 요청의 몸 (JSON)
• 사용 VALID USER_ID/상태 값 =
• 세 끝점 각 가능한 상태 "값에 대해 하나의 생성 :/사용자 /? USER_ID/상태 :
• /사용자/유효 USER_ID/상태/:
  • /사용자 /를/
  • /사용자/not_valid : USER_ID/상태/to_validate

감사합니다.

Answer 1

상태가 쿼리 가능하지 않은 경우,/user/: user_id와 같은 사용자 엔티티 자체의 일부로 상태를 가질 수도 있고 상태를 업데이트하기 위해 Patch (JSON 페이로드와 함께)를 수행 할 수도 있습니다. 일반적으로 하위 경로 자체를 하위 리소스로 쿼리하거나 독립적으로 업데이트 할 수있는 경우 중첩 된 경로를 선호합니다. 그래서 누군가가 사용자의 상태를 필요로한다면,/user/: user_id의 GET 결과를 기대하지 않을까요? 아니면/user/: user_id/status에 또 다른 GET 호출을해야합니까? 나는/상태 경로가 좋은 생각이 아닐 수도 있다고 생각한다.

또한 상태와 같은 것을 추가하면 미래에 이름, 주소 등을 업데이트해야하는 경우 어떻게됩니까? 모든 필드에 대해 새로운 하위 경로를 계속 추가하고 싶지는 않습니까? 또한 URL 경로에 enum-like 하위 경로 (valid/not_valid 등)를 사용하는 것이 올바른 일은 아닌 것 같습니다. JSON 페이로드에 포함 시키면 스키마 아래에 올 것이므로 열거 형을 새로 추가 할 경우를 대비하여 버전을 멋지게 버전화 할 수 있습니다. 이 URL을 URL의 일부로 갖는 것은 클라이언트가 새로운 경로에 대해서도 알 필요가 있음을 의미합니다.

한편, API의 유용성에 대해서도 고려해야합니다. REST API를 설계 할 때 일반적으로 따라야 할 규칙 중 하나는 다음과 같습니다. 2 분 정도 후에 클라이언트를 내 API와 통합하고 성공적으로 통합하기 위해 알아 두어야 할 것들의 수를 최소화해야합니다. 모든 표준과 규범은 유용성에 이차적 일 수 있습니다.