Question

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

example.com/request/distribution

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

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

这被视为“RESTful”网址还是有更好的方法更有意义？任何意见都非常感谢。

BTW，Python是首选语言。谢谢！

Answer 1

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

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

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

您的资源由多个必填段标识的事实是URI设计的重要组成部分。正如Anton指出的那样，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。更改URI是uncool，对于您和使用API的开发人员来说很痛苦。因此，如果您需要将身份验证传递给后端，则可能应该使用GET参数或HTTP标头（例如，AWS S3 API，allows both）。

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

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

在研究答案时，发现了一个关于RESTful API的精彩演示文稿：Designing HTTP Interfaces and RESTful Web Services。

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？

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

4 个答案: