我将很快设计一个RESTful API,因此我需要对其进行描述,以便让其他人开始使用它来实现客户端.
我看了一下,但不幸的是,我没有找到任何描述基于Web的RESTful服务的标准化形式.我正在寻找的东西就像JavaDoc,虽然它不必由任何类型的代码生成.我也不是在谈论类似WADL的东西,我宁愿想要一些我可以提供的人类可读的文档.
由于RESTful基于Web的服务的性质,标准化文档应该很容易.它应该只列出可用的资源,相应的URI,允许的方法,内容类型并描述可用的操作.你有什么建议吗？
在此先感谢您和Greets
由于RESTful基于Web的服务的性质,标准化文档应该很容易.它应该只列出可用的资源,相应的URI,允许的方法,内容类型并描述可用的操作.你有什么建议吗？
这绝对是记录REST服务的错误方法.
您永远不应该枚举资源的URI,因为这会鼓励客户端将这些URI硬编码到客户端代码中.这会在客户端和服务器之间创建不必要的耦合.应该基于从服务根URI导航来发现URI.根URI是唯一应记录的URI.文档应侧重于描述返回的表示中的信息和链接.如果您从根URI返回的表示开始,则可以描述媒体类型以及该文档中可能提供的链接.
使用某种别名在客户端和服务器之间创建一个间接层是很重要的.如果您遵循atom:link标准来定义链接,那么rel属性将成为标识符.但是,还有其他定义链接的方法,例如,图像嵌入html的方式.图像标记可以具有Id和href.Id标记应用于标识您希望访问URL的图像.
最终结果是您在某些表示的上下文中定义API中的所有端点.完整的API由返回的表示集和连接它们的链接定义.
所以你可能会问,有什么区别？为什么不创建端点列表？这有几个原因,
由于客户端使用别名访问这些链接,因此可以在不影响客户端的情况下完全更改站点的整个URL结构.这使得所有无穷无尽的"构建我的分层URL的最佳方式"问题几乎无关紧要.你可以尝试一种方式,如果它不起作用,只需更改它,你不会破坏任何客户端代码或必须更改任何文档!
它不仅仅是您可以更改的URI的路径部分.您也可以更改主机.想象一下,您的应用程序开始获得比预期更多的使用率,您可以轻松地将所有图像或视频资源的主机更改为指向其他服务器.您甚至可以通过返回不同的主机来提供简单的负载平衡 由于RESTful API是无状态的,因此哪个服务器响应请求并不重要.此功能对于许多场景非常有用:将HTTPS内容移动到专用服务器上,根据客户端位置在地理上分发请求,将应用程序的功能垂直分区到不同的服务器上.
仅仅因为表示可能返回一个链接,并不意味着它总是会.服务器只能根据当前资源状态返回允许的链接.当与服务器资源交互时需要遵循特定协议时,这可能非常有用.客户端代码不需要理解协议的规则,它可以仅向用户呈现服务器可用的链接.
大多数自动化文档REST服务工作无效的原因是因为统一的界面不需要记录简单的东西.一旦理解了HTTP(参见RFC2616),就可以理解API的所有机制.剩下的就是无法生成的真正有趣的域特定信息.
从好的方面来看,文档应该更短.任何额外的可用时间都应该用于提供如何针对常见场景导航API的示例.
没有标准,只是公开辩论.InfoQ上有一篇有趣的文章:描述RESTful应用程序.
京公网安备 11010802040832号 | 京ICP备19059560号-6 