REST API的根页面的最佳实践是什么？

Question

我想知道REST Web服务的根端点是否有一些最佳实践？我的意思是，这是否应该是关于API本身使用的简短文档？应该是描述所有可用方法的XML文档吗？它应该仅返回“未知方法”？

Answer 1

这个问题不清楚。我想这意味着所有API方法都在下面的目录。例如，Flickr API的根目录是 http://api.flickr.com/services/rest/.

有关访问Flickr API的项目的示例，请参阅 Python-Flickrapi

Answer 2

这个问题对我来说很清楚。

我认为它应该以404的速度做出响应。如果没有与根路径相关的资源，那么没有什么可返回的。

如果您觉得404没有帮助，那么也可以返回文档的URL。

Answer 3

• nerddinner.com¹
• 太阳云API
• 推特
• 保罗·詹姆（Paul Jame）的文章
• Mediawiki的API²

---

1. Nerddinner使用WCF数据服务，这是正确实施Restful服务的好方法。我要指出的原因，而不是直接WCF数据服务是因为它是一个公共网站，您可以使用它。 2. MediaWiki不是一个很好的例子，因为他们正在通过URI进行动作，但从技术上讲，这是一项宁静的服务，并且展示了很多有趣的想法。

Answer 4

REST API的root点点是调度程序服务后URL的第一个斜率IE“/”定义的API。它包含资源列表的所有获取（主要是所有数据库表的获取），此列表进一步包含所有项目，并且在单个项目中，将删除，put/put/patch和self get url。从而实施Hateos。

Answer 5

休息应该是自我描述的，因此在我看来，要使根显示错误是差的设计。我喜欢root可以包含允许您导航其余API的信息。因此，例如，根可能包含指向产品类别列表的链接，API用户可以从中选择一个类别，然后选择一个产品列表等。描述API的自我意味着更少的文档来编写和保持更新！