设计RESTful URI

Question

我正在创建一个RESTful API。我阅读了相关文献。

http://microformats.org/wiki/rest/urls

但是这个网站不能给我足够的“好”的实践来设计我的API。具体而言，我将编写一个API（目前仅有GET方法），该API将提供将地理坐标进行转换的功能。

例如：地理哈希是坐标的单一值表示，因此 /convert/geohash/u09tvkx0.json?outputformat=latlong 是有意义的。另一方面，/convert/latlong.xml?lat=65&long=13&outputformat=UTC 需要两个输入值。

看看我的“问题”？什么样的API需要多个输入参数才算合适？

（尝试通过“分析”Twitter和FF来“识别”良好的实践，但失败了）

- JohnDoe

Answer 1

就技术上而言，使用查询字符串参数与不使用在被视为“技术上”正确的REST URI之间没有区别。在RFC 3986中指出：

查询组件包含非分层数据，与路径组件中的数据（第3.3节）一起用于标识资源

这就是你难以找到明确的“最佳实践”的原因。尽管如此，许多REST API会将多个参数嵌入URI中，而不使用查询字符串。例如，为了识别汽车的品牌和型号，您会看到URI类似于cars.com/honda/civic的网站。在这种情况下，两者之间的关系非常明显，因此将所有内容放在URI中是“可黑客化的”。如果只有一个参数唯一地标识资源，则仅使用非查询字符串方法更容易实现；但如果是像搜索查询这样的东西，那么我可能会将其保留在查询字符串中。这个SO question也有一个有趣的讨论关于不同的方法。

在上面的例子中，我会坚持使用查询字符串参数。尽管REST通常具有更直观的URL，但这并不是REST所关心的。REST更关注超媒体和HATEOAS。

- Steve Michelotti

---

谢谢您的解释！它填补了我对REST“设计原则”的概念上的空白。我不知道HATEOAS，但我喜欢这种态度。 - JohnDoe

Answer 2

在设计REST API时，有一些最佳实践需要遵循：

1. 抽象与具体
2. CRUD操作
3. 错误处理
4. API版本控制
5. 过滤
6. 安全性
7. 分析
8. 文档化
9. 稳定性和一致性
10. URL结构

阅读更多

- Techie