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

92

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를 더 잘 이해할 수 있도록 어떤 경로를 선택해야하는지 알고 싶었습니다.

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

rest  url  jax-rs  url-scheme  url-pattern 
— shahshi15
소스
1
나는 이것이 조금 오래되었지만 비슷한 리소스를 찾고 있다는 것을 알고 있습니다.이 질문과 당신이 찾고 있던 질문을 우연히 발견했습니다. 나는 이것이 하나라고 믿는다 stackoverflow.com/a/9743414/468327
— Joel Berger

답변:

104

내 경험상 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금지 된 사용자 목록을 반환 할 수 있습니다.

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

— DannyMo
소스
입력 해 주셔서 감사합니다. 사실 당신이 옳습니다. "RESTful java with Jax-rs"책에서 # 1을 읽은 것 같지만 다소 문맥에서 벗어났습니다. 그러나 나는 stackoverflow 자체에 대한 질문 중 하나에 대한 대답으로 읽은 것을 매우 분명히 기억합니다 (동료들에게도 증명하기 위해 그 링크를 찾기 위해 매우 열심히 노력하고 있다고 말할 때 나를 믿으십시오 :)) 그리고 # 2는 정확히 내가 무엇이 었는지 찾고있는. 디자인에 대한 피드백. 감사합니다!
— shahshi15
추신 : 여기에 게시하는 것이 규칙에 위배되는지 확실하지 않지만 다른 질문 중 하나에 대해 조명을 던질 수 있습니까? 부디? :) stackoverflow.com/questions/20508008/…
— shahshi15
에 대한 중복성에 대한 설명을 명확히하기 /users/id/{id}위해 확장 기능을 허용하고 여러 식별자 (id, guid, name)를 통해 하나의 리소스에 액세스 할 수 있습니다. 또한 응답 여기
— 다니엘 Dubovski에게
4
내 대답은 예를 들어 특정 사용자를 참조하는 적절한 방법은 / users / {id}입니다. 사용자의 고유 식별자가 아닌 특정 이메일 주소로 사용자를 찾으려면 리소스별로 특정 리소스를 식별하는 것이 아니라 사용자 모음을 필터링하는 방법이므로 / users? email = {email}을 수행합니다. 식별자는 / users / {id}입니다.
— Kevin M
좋은 대답! 그것에 대한 엄지 손가락. REST는 자원 매핑이 같은해야하므로 이름을 중심해야로서 내가 할 추천 할 것입니다 유일한 것은 당신의 API을 약간 수정 한 것 또한 : GET /user/1234이 아니라GET /users/123
— 새미
38

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

/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

— 비나이 사니
소스
답장 주셔서 감사합니다 vinay. 그러나 우리가 이것을 다른 관점에서 생각한다면, {id}와 마찬가지로 {email}은 항상 하나의 결과를 반환 할 것입니다. 실제로 검색하는 경우 이메일뿐만 아니라? id = {id}를 사용하지 않는 이유는 무엇입니까? 어쨌든 일관성이 있는지 궁금합니다. 추신 : 새로운 stackoverflow, 하나의 답변 만 할 수 있다는 것을 몰랐습니다. 하지만 답장을 보내 주셔서 감사합니다! 감사합니다. : 어쩌면 당신이뿐만 아니라 하나 나를 도울 수 stackoverflow.com/questions/20508008/...
— shahshi15
7
여기서 API 디자인의 "디자인"측면이 작용합니다. 리소스에는 전용 위치가 있어야합니다. 위치는 어디입니까? 위치는 ID로되어 있습니까? 그렇다면 id로 "검색"하지 않고 id로 "get"합니다. 그러나 다른 모든 것으로 검색합니다. 물론 여기에는 엄격한 규칙이 없습니다. 그것은 :) 단지 관점이다
— 인 Vinay Sahni에게
6
또한 이런 식으로 API가 더 안정적이라고 주장합니다. ID가 고유하다는 것을 정말로 알고 있지만 이메일 주소에 대해 정말로 확신합니까? 고유하더라도 사용자가 변경할 수 있으므로 영구적이지 않을 수 있습니다. 따라서 / users? email = {email}은 이것이 실제로 쿼리이며 영구 식별자가있는 리소스에 대한 액세스가 아님을 분명히합니다.
— lex82
나는 이것이 실제로 더 정답이라고 믿습니다. 이메일 주소로 컬렉션을 필터링하는 것은 와일드 카드 기반 일 수 있으므로 항상 하나의 결과 만 반환하지는 않습니다.
— Kevin M
@VinaySahni /user?by=email&email="abc@pqr.com "/ user? by = id & id ="xashkhx "/ users? filterA ="a "& filterB ="b "(복수형 ) 여러 사용자
— Shasak
2

사용자 리소스 정보

경로에서 /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에 이메일 주소를 입력하여 이메일 주소를 업데이트 할 수 있습니다 .

— 이울다
소스
당사 사이트를 사용함과 동시에 당사의 쿠키 정책과 개인정보 보호정책을 읽고 이해하였음을 인정하는 것으로 간주합니다.
Licensed under cc by-sa 3.0 with attribution required.