[rest] REST API 디자인-매개 변수는 다르지만 URL 패턴은 동일한 REST를 통해 리소스 가져 오기

Program / 글쓴이

REST URL 디자인과 관련된 질문이 있습니다. 여기에서 몇 가지 관련 게시물을 찾았습니다. 동일한 리소스의 다른 RESTful 표현 과 여기 : 다른 필드에서 리소스를 GET하는 RESTful URL 이지만 모범 사례가 무엇인지 그리고 그 이유에 대한 응답은 명확하지 않습니다. 여기에 예가 있습니다.

“사용자”리소스를 나타내는 REST URL이 있습니다. ID 또는 이메일 주소로 사용자를 가져올 수 있지만 URL 표현은 둘 다 동일하게 유지됩니다. 많은 블로그와 책을 살펴보면 사람들이 여러 가지 방법으로 이것을하고 있음을 알 수 있습니다. 예를 들면

책과 스택 오버플로 어딘가 에서이 연습을 읽으십시오 (링크를 다시 찾을 수없는 것 같습니다)

GET /users/id={id}
GET /users/email={email}

많은 블로그에서이 관행을 읽으십시오.

GET /users/{id}
GET /users/email/{email}

쿼리 매개 변수는 일반적으로 URL로 표시되는 리소스의 결과를 필터링하는 데 사용되지만이 방법도 사용되는 것을 보았습니다.

GET /users?id={id}
GET /users?email={email}

내 질문은 이러한 모든 관행 중에서 API를 사용하는 개발자에게 가장 적합한 방법은 무엇이며 그 이유는 무엇입니까? REST URL 디자인 및 명명 규칙에 대해서는 정해진 규칙이 없다고 생각하지만 개발자가 API를 더 잘 이해할 수 있도록 어떤 경로를 선택해야하는지 알고 싶었습니다.

모든 도움을 주셔서 감사합니다!

답변

내 경험상 GET /users/{id} GET /users/email/{email}가장 일반적인 접근 방식입니다. 또한 사용자가 제공된 id또는 email. 나도를 보는 것에 놀라지 않을 것입니다 GET /users/id/{id}(내 의견으로는 중복되지만).

다른 접근 방식에 대한 의견

  1. GET /users/id={id} GET /users/email={email}
    • 나는 이것을 본 적이 없다고 생각합니다. 그리고 만약 내가 본다면 그것은 매우 혼란 스러울 것입니다. 경로 매개 변수로 쿼리 매개 변수를 모방하려는 것과 거의 같습니다.
  2. GET /users?id={id} GET /users?email={email}
    • 필터링을 위해 쿼리 매개 변수를 사용하는 것에 대해 언급했을 때 머리를 찔렀다 고 생각합니다.
    • 그것은 이제까지 감각으로이 자원 전화를 만들 것 모두id 하고 email(예를 들면 GET /users?id={id}&email={email})? 그렇지 않다면 이와 같은 단일 리소스 방법을 사용하지 않을 것입니다.
    • 필터링을위한 선택적 쿼리 매개 변수를 사용하여 사용자 목록 을 검색하는이 방법을 기대 하지만 id, email또는 매개 변수 중에 고유 식별자가있을 것으로 예상하지 않습니다 . 예 : GET /users?status=BANNED금지 된 사용자 목록을 반환 할 수 있습니다.

관련 질문 에서이 답변 을 확인하십시오 .

답변

이를 실용적으로 살펴보면 다음과 같은 사용자 모음이 있습니다.

/users   # this returns many

각 사용자에게는 전용 리소스 위치가 있습니다.

/users/{id}    # this returns one

또한 사용자를 검색하는 여러 가지 방법이 있습니다.

/users?email={email}
/users?name=*bob*

이들은 모두 / users에 대한 쿼리 매개 변수이므로 목록이 1 인 경우에도 모두 목록을 반환해야합니다.

여기에 실용적인 RESTful API 디자인에 대한 블로그 게시물을 작성했습니다. 여기에서 이에 대해 설명합니다. http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api

답변

사용자 리소스 정보

경로에서 /users항상 반환되는 사용자 리소스 모음을 얻습니다.

경로에서 /users/[user_id]몇 가지 일이 발생할 것으로 예상 할 수 있습니다.

  1. 식별자 [user_id]로 사용자 리소스를 나타내는 단일 리소스를 가져와야합니다.
  2. ID가 [user_id] 인 사용자가없는 경우 찾을 수 없음 404 응답 또는
  3. 요청 된 사용자 리소스에 액세스 할 수없는 경우 금지 된 401 입니다.

각 싱글 톤은 경로와 식별자로 고유하게 식별되며이를 사용하여 리소스를 찾습니다. 싱글 톤에 여러 경로를 사용할 수 없습니다.

/users쿼리 매개 변수 ( GET매개 변수)를 사용하여 경로 를 쿼리 할 수 있습니다 . 그러면 요청한 기준을 충족하는 사용자가있는 컬렉션이 반환됩니다. 반환되는 컬렉션에는 응답에서 식별 리소스 경로와 함께 사용자 리소스가 모두 포함되어야합니다.

매개 변수는 컬렉션의 리소스에있는 모든 필드가 될 수 있습니다. firstName, lastName,id

이메일 정보

이메일은 리소스 또는 사용자 리소스의 속성 / 필드 일 수 있습니다.

-사용자의 재산으로 이메일 :

필드가 사용자의 속성 인 경우 사용자 응답은 다음과 같습니다.

{
  id: 1,
  firstName: 'John'
  lastName: 'Doe'
  email: 'john.doe@example.com'
  ...
}

즉, 이메일에 대한 특별한 엔드 포인트가 없지만 이제 다음 요청을 전송하여 이메일로 사용자를 찾을 수 있습니다
/users?email=john.doe@example.com. 이메일이 사용자에게 고유하다고 가정하면 이메일과 일치하는 하나의 사용자 항목이있는 컬렉션을 반환합니다.

-리소스로서의 이메일 :

그러나 사용자의 이메일도 리소스라면. 그런 다음 /users/[user_id]/emailsid가있는 사용자의 이메일 주소 모음을 반환 하는 API를 만들 수 user_id있습니다. /users/[user_id]/emails/[email_id]user_id와 [ ’email_id’]가있는 사용자의 이메일을 반환합니다. 식별자로 사용하는 것은 귀하에게 달려 있지만 정수를 고수합니다. 삭제할 이메일 DELETE을 식별하는 경로 로 요청을 보내 사용자 의 이메일을 삭제할 수 있습니다. 예를 들어 DELETEon /users/[user_id]/emails/[email_id]은 user_id를 가진 사용자가 소유 한 email_id를 가진 이메일을 삭제합니다. 해당 사용자 만이 삭제 작업을 수행 할 수 있습니다. 다른 사용자는 401 응답을 받게됩니다.

사용자가 하나의 이메일 주소 만 가질 수있는 경우에는 /users/[user_id]/email
이것이 단일 리소스를 반환합니다. 사용자는 PUT해당 URL에 이메일 주소를 입력하여 이메일 주소를 업데이트 할 수 있습니다 .

답변