理想的 API 路由

Question

我正在编写一个 API。到目前为止，我一直在使用路线：

http://api.com/resource

然后我将我想要对 json 字段中的资源执行的操作传入并从那里开始。从程序员和用户的角度来看，这是理想的还是更可取的情况？

或者，

会是这样的：

http://api.com/resource/action

更有用、更宁静、正确（任你挑选）。还是根本不重要？它按原样工作，但我的目标是公共消费，我想在它变得更难改变之前解决我不知道的任何问题。

编辑：

要添加更多细节，我不关心的操作是 GET、POST 等。我有一条路线：

http://api.com/thing

这是一个 POST 路由，它创建了一个东西。此时事物并未存储在数据库或任何地方，因此创建的事物会立即与响应一起返回。用户可以指定返回的东西涂上颜色：红色、黄色或绿色。从用户的角度来看，将颜色要求指定为上述帖子数据的一部分或具有如下路线是否更有用：

 http://api.com/thing/red

发帖返回一个红色的东西。

Answer 1

基本上，action 不需要指定（在 URL 或发送的数据中），因为 HTTP 动词在 REST 方法中用于描述对资源执行的操作。因此，您的两个解决方案并不是真正“符合 REST 标准”。你首先应该做的是将你的路由 http://api.com/resources 与一些 HTTP 动词结合起来，以便：

• 创建资源是：POST http://api.com/resources
• 读取资源是：GET http://api.com/resources/
• 更新（实际替换）资源是：PUT http://api.com/resources/
• 删除资源为：DELETE http://api.com/resources/

像往常一样，遵循约定更好。对于喜欢约定和最佳实践的程序员来说，您的两种解决方案并不理想。但是，您的第二个解决方案是可读且明确的。这意味着，如果您真的想在两种解决方案之间进行选择，第二种似乎更好。但是，如果您想更新您的 API 以遵循更多 REST 约定，您应该将您的 resource 视为真实资源并使用 HTTP verbs。

我向您推荐这两个关于 REST API 的演示文稿：

• http://fr.slideshare.net/Wombert/designing-http-interfaces-and-restful-web-services-dpc2012-20120608
• https://speakerdeck.com/u/nicola/p/developing-restful-web-apis-with-python-flask-and-mongodb

您可能对这个其他问题和我给出的答案感兴趣：Resource and Action URI convention for REST。

编辑：根据您的新问题，将所有数据作为帖子数据发送，甚至您的颜色。会更加一致。为什么它应该有所不同呢？只有在描述不同的资源时才应该更改 URI。如果颜色只是 thing 的属性，那么您没有描述两个资源，您应该将颜色与所有其他发布数据一起发送。