api - REST API GET 方法

Question

根据 REST API 设计建议，必须通过 id 获取用户

GET /users/{id}

如何通过唯一电话号码获取用户？

GET /users/phone/{number}

或者

GET /users/?phone=xxxxxxxxxxx

或者

GET /phones/{number}/users

还是别的什么？

或者例如获取有限制的最后用户评论:

/users/{id}/comments/limit/{limit}

或者

/users/{id}/comments/?limit='xx'

在这种情况下有限制或建议吗？

哪种 HTTP 方法更适合发送请求以进行某些操作(例如发送短信)。

Answer 1

你的问题有很多不同的方面，所以我挑了一些，希望答案对你有所帮助。

一般来说，URI 是某个资源的唯一标识。此外，“好的 REST-API URI”仅包含名词(“命名”资源)，而不包含动词(应该对资源做什么)。 URI 参数可用于参数化资源表示，例如排序或过滤。

在你的例子中，

/users/{id}/?limit='xx'

将是获取某些子资源列表(可能是用户评论)的有效方法，但 URI 上没有任何内容涉及特定属性或子资源(例如评论)。

更有意义的资源 URI 是

/useres/{id}/comments/?max=100&sort=asc

在这种情况下，第一部分(users/{id}/ comments/)标识资源，而参数用于参数化其表示。 正确的 URI 不依赖于 URI 参数来唯一标识资源。

URI 中的过滤条件可以类似地处理。您可以将它们放在参数中，但这可能会导致多个和/或复杂过滤器出现问题，例如

GET /useres/?phone=1234&phonemode=startswith&name=foo&namemode=contains

一种方法可能是创建一个过滤器(可能只是暂时的)，然后使用后续的 GET 请求检索过滤后的信息，如下所示:

POST /users/filter
   name='mycomplexfilter'
   poperty='name'
   value='foo'
   mode='contains'        

GET /useres/filter/mycomplexfilter

希望这有助于阐明这个话题

[编辑]
有关常用 HTTP 方法(又名动词)的解释，请参阅此摘要: Which HTTP methods match up to which CRUD methods?

See this question 类似的答案。

应该使用 POST(例如到资源 URI/notifications)请求启动服务器发送的通知(可能通过 SMS)，并在有效负载中包含文本和收件人。 HTTP header 可用于指示所需的通知类型，而 HTTP 状态代码则指示发送尝试是否成功。状态码 201 表示消息发送成功，同时返回新创建资源的 URI。

客户端请求:

POST /notifications

recipient="+0049123456789"
text="this is the SMS text"

服务器响应:

201 - Created
Location: /notifications/9876