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方法更好地发送请求以执行某些操作（例如短信发送）？

- yaahor

---

欢迎来到StackOverflow！您的问题目前过于模糊，无法提供有意义的答案。您是在询问特定的REST API还是API设计的一般方法？请澄清问题，并在适当的情况下添加其他标签。 - mfitzp

这是一道品味问题。无论您选择哪种方法，请尽量在所有资源网址中始终保持一致。 - Boris Pavlović

我更新了我的答案以适应你的编辑。 - tasel

Answer 1

您的问题涉及许多不同的方面，因此我挑选了一些希望对您有所帮助的答案。

一般来说，URI是某个资源的唯一标识符。此外，“良好的REST API URI”仅包含名词（用于“命名”资源），而不包含动词（用于描述应该对资源执行什么操作）。URI参数可用于参数化资源表示形式，例如排序或过滤。

在您的示例中，

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

将是获取某些子资源列表的有效方式（可能是用户的评论），但此处没有任何内容指向特定的属性或子资源（例如评论）。

更有意义的资源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方法（也称为动词）的解释：哪些HTTP方法与哪些CRUD方法相匹配？

请参阅此问题以获取类似的答案。

发起服务器发送通知（可能通过短信）应使用POST请求（例如，对于有效负载中的文本和接收者，请使用ressource URI /notifications）。 HTTP标头可用于指示所需的通知类型，而HTTP状态代码则指示发送尝试的成功。状态代码201表示消息已成功发送，并返回新创建资源的URI。 客户端请求：

POST /notifications

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

服务器回应：

201 - Created
Location: /notifications/9876

- tasel