Myo*_*bis 6 versioning documentation rest documentation-generation hateoas
我正在通过Http设计类似REST的API.
我需要API客户端(应用程序,而不是浏览器)来关注链接(HATEOAS),而不是构建它们.
此外,由于某些可能不同意的原因,我仍然会使用可读的URL .但是,如果存在相当的方式文档的URL模板(像 这些 的人),我不认为这是正确的做法,因为它可以清楚地吸引和合法的开发人员可以构建自己的网址.
那么,如何以尊重HATEOAS的方式记录API？
我们经常发现与HATEOAS相关的可发现性.
说实话,我不认为这在现实生活中是不够的:商业概念是多重的,微妙的理解和客户开发人员不是你的队友.
有意义的名字显然是不够的.
开发人员需要制作客户端应用..
那么,如何记录这个？
相关概念:
使用Intent,Versioning,Level 3 API进行设计
首先,可读URI并没有任何问题,用户可以通过手工构建URI轻松浏览您的API.只要他们不使用它来推动实际的API使用,这根本不是问题,甚至是Roy Fielding自己鼓励的.在URI必须不透明的基础上对此的不同意见是一个神话.引用菲尔丁自己的事情:
也许我错过了一些东西,但是因为有几个人说REST意味着URI不透明,我的猜测是传说已经开始了,我需要让它休息(没有双关语).
REST不要求URI是不透明的.在我的论文中唯一出现不透明这个词的地方就是我抱怨饼干不透明的地方.事实上,RESTful应用程序在任何时候都被鼓励使用具有人性意义的分层标识符,以便最大限度地使用超出原始应用程序预期的信息的偶然使用.
服务器仍然需要构造URI并且客户端最初通过超文本响应发现这些URI,无论是在创建资源的正常过程中还是通过某种形式的查询导致超文本列表.但是,一旦提供了该列表,人们可以并且确实预期该名称空间中其他/未来资源的名称,就像我经常直接在位置栏中键入URI而不是通过一些设计不良的交互式多页面界面股票图表.
http://osdir.com/ml/web.services.rest/2003-01/msg00074.html
如果您需要您的客户开发人员遵循超链接而不是手工构建URI,根据我的经验,我认为最好的方法是将其作为您工作环境中的文化变革进行推广.在我的情况下,我有一个支持性的经理,所以它更容易.您应警告他们URI名称空间受服务器控制,URI可能随时更改.如果他们的客户因为没有遵守而破产,那不是你的责任.通过某种研讨会或演示来解释HATEOAS如何运作以及为每个人带来的好处也很有帮助.我注意到很多街头REST开发人员认为它是多余的,直到他们真正得到它.
现在,为了解决您的主要问题,您不应该记录API,您应该将文档工作重点放在媒体类型上.再次引用菲尔丁:
REST API应该花费几乎所有的描述性工作来定义用于表示资源和驱动应用程序状态的媒体类型,或者为现有标准媒体类型定义扩展关系名称和/或启用超文本的标记.在媒体类型的处理规则的范围内(并且在大多数情况下,已经由现有媒体类型定义)应该完全定义用于描述在感兴趣的URI上使用什么方法的任何努力.[失败在这里意味着带外信息驱动交互而不是超文本.]
http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
这意味着,您应该为表示提供自定义媒体类型,而不是记录API端点或URI,您应该记录这些媒体类型以及其中可用链接的操作.例如,假设您有一个问答网站的API,如StackOverflow.而不是让API文档告诉他们应该在问题的表示中POST到rel:answers链接以便与当前用户一起回答它,您的问题应该具有媒体类型application/vnd.yourcompany.question+xml和该媒体的文档-type你说一个POST到一个rel:answers http链接将回答这个问题.
我不知道有任何现有的工具,但根据我的经验,可以使用任何可用于从抽象模型生成文档的工具.
我不知道你的API生态系统是怎样的,但对我来说有用的是有一个通用的文档,对REST有一个温和的介绍,解决一些误解,以及你的模式的详细一般用法,应该适用于任何API .之后,每个服务器都应该有自己的文档,专注于媒体类型.
我不喜欢在text/html表示中返回文档的想法,因为那应该代表资源本身,但我喜欢有一个rel:doc链接指向你的HTML文档的想法.