具有多个必需参数的RESTful URI的最佳设计是什么？

Question

我想看看是否有更多经验丰富的Web服务资深人士可以评论在我需要强制参数的地方设计RESTful URI的最佳方法。 举个例子，我想设计一个请求数据的URI：

example.com/request/distribution

但是，根据我的理解，方法是更多数据应该返回更高级别，而如果应用更具体的URI关键字将返回更详细的数据，但在我的情况下，我需要至少3个值才能实现。 这3个值将是日期值，帐户值和专有分发代码值。 例如：

example.com/request/distribution?acct=123&date=20030102&distcode=1A;1B;1C

这被认为是一个“RESTful”URL还是有更好的方法更有意义？ 任何输入都非常感谢。

顺便说一下，Python是首选语言。 谢谢！

Answer 1

根据定义，URI不能自己“unRESTful”，因为URI规范是由REST架构风格引导的。 如何使用 URI可能违反REST样式：

1. 不遵循“客户端 - 服务器”约束; 例如，通过使用WebSockets实现服务器推送。
2. 不遵循“资源识别”约束; 例如，使用URI的一部分来指定控制数据或资源元数据，而不是坚持识别资源，或者通过除URI之外的某种机制（如会话状态或其他带外机制）识别资源。
3. 不遵循“通过陈述来控制资源”的约束; 例如，通过使用URI的查询字符串部分来传输状态。
4. 不遵循“自描述信息”约束; 例如，使用HTTP GET修改状态，或使用Content-Type为“text / html”传输JSON。
5. 不遵循“超媒体作为应用程序状态引擎”的约束; 例如，不提供要跟随的用户代理超链接，而是假设它将使用带外知识构造它们。
6. 不遵循“分层系统”约束，要求客户端了解服务器工作方式的内部细节（特别是要求客户端在请求中提供它们）。

以上都不一定是糟糕的选择 。 它们可能是您系统的最佳选择，因为它们可以培养某些架构属性（例如效率或安全性）。 它们只是REST风格的一部分。

您的资源由多个必需段标识的事实是URI设计的重要组成部分。 正如Anton指出的那样，在example.com/request/distribution?acct=123&date=20030102&distcode=1A;1B;1C和例如example.com/accounts/123/distributions/20030102/1A;1B;1C ; example.com/request/distribution?acct=123&date=20030102&distcode=1A;1B;1C ; example.com/accounts/123/distributions/20030102/1A;1B;1C之间的选择纯粹是数据设计之一，而不是URI层本身的问题。 例如，响应对前者的PUT，POST或DELETE请求没有任何错误。 未能跟随任何一个链接的客户端将被视为已损坏。 期望通过除超媒体响应以外的某种方式使客户端可用的系统将被视为“不可靠”。

Answer 2

最好先从资源方面创建RESTful API，而不是URI。 它与您的数据设计有关，而不是与您选择的语言有关。

例如，您有一个分发资源。 您希望在基于Web的API中表示它，因此它需要具有适当的唯一资源标识符（URI）。 它应该简单，可读，并且不太可能改变。 这将是一个很好的例子：

http://example.com/api/distribution/<some_unique_id>

在将更多内容和层次结构放入URI之前，请三思而后行 。

随着数据模型或身份验证方案的发展，您不希望更改URI。 对于使用API​​的开发人员和开发人员来说，更改URI非常容易 。 因此，如果您需要将身份验证传递给后端，您可能应该使用GET参数或HTTP标头（例如，AWS S3 API 允许这两者 ）。

过多地考虑GET参数（例如， http://example.com/api/distribution/?id=<some_unique_id> ： http://example.com/api/distribution/?id=<some_unique_id> ）似乎是一个坏主意，但IMO并不重要[0] - 只要您可以访问API文档并获取最新信息。

[0]更新：至少对于只读API。 对于CRUD API，正如@daniel指出的那样，当您拥有上述第一个示例中的端点时，它会更方便。 这样，您可以通过为/api/distribution/<id>各个资源启用GET，PUT，DELETE以及POST到/api/distribution来创建新的发行版，从而很好地使用HTTP方法。

在研究答案时，发现了一个关于RESTful API的精彩演示： 设计HTTP接口和RESTful Web服务 。

Answer 3

RESTful方式是将数据表示为资源，而不是请求的参数：

example.com/distribution/123/20030102/1A;1B;1C

Answer 4

当你想到RESTful时，大多数时候你也应该考虑CRUD。

example.com/request/distribution?acct=123&date=20030102&distcode=1A;1B;1C

GET-Request可以显示某些内容（CRUD中的R）。

但是你对CUD-Parts考虑了哪些URL？