在我的公司,我们开始分支到Web API来访问和更新我们的数据; 最初是为了合作伙伴,但未来很可能对公众有利.目前API的外观(例如SOAP,REST,RPC)是完全开放的,我们还没有做出任何决定,所以我对人们认为很好的Web API的例子以及你为什么这么认为感兴趣那.
我感兴趣的是使用不同语言的人的意见(我们可能会向使用多种平台的人提供API,特别是包括.NET,Java,ActionScript和JavaScript)关于您认为好的Web API例子,你有很好的经验.
我想谈谈的一些观点:
您更喜欢SOAP类型服务还是REST/RPC风格服务？我怀疑拥有平台支持的人(例如.NET,Java)会更喜欢SOAP,而使用没有平台支持的语言的人会更喜欢其他人,但我想验证这个假设.
您是否关心API是否实际上是REST还是它是一个普通的旧式RPC GET/POST？如果是这样,你为什么关心？API是否正确描述自身(即,如果它是RPC样式,并不声称是RESTful)更重要,而不是它实际上是两者之一吗？
我们需要验证谁在使用该服务.我一直在研究Amazon S3身份验证,它使用公共标识符和私有令牌,用于将请求的参数哈希到验证令牌中(这也类似于flickr).您以前是否使用过这种类型的身份验证,以及如何继续使用它？您是否发现有问题的哈希算法(即您的平台不支持)？您希望在HTTP标头或URI中发送散列吗？
如何处理版本控制？有一个/v1/类型子目录以便可以同时添加未来的版本,或者你会做一些不同的事情,如请求有效负载或查询中的版本,这是一个好主意吗？您期望支持的API版本需要多长时间(例如,如果引入了v2,那么您在v1的生命周期内的期望是什么).
此外,任何其他意见和要点将有用.
我故意对我们正在实施的API的实际类型保持模糊,因为我正在寻找人们认为好的API和实现机制的一般指导,所以这篇文章及其答案对更多人有用在将来.
注意:我已搜索过,无法找到关于此的一般性问题 - 它们似乎都特定于某种类型的API - 但如果它是重复的,请告诉我.此外,如果它应该是社区维基(我认为人们应该得到答案的信用,所以我没有做到一个)然后请让我知道,我会改变它.
这是我的看法.
虽然来自Java的观点,但我实际上更喜欢REST.具有多个名称空间的SOAP信封及其复杂的结构令人憎恶.它试图解决大多数想象中的问题,并没有有效地解决任何问题.关于我发现有用的SOAP的唯一事情是它有授权和错误的标准.另一方面,通过在根XML元素中包含四个标准属性 - username,password,errorCode,errorDescription,可以更容易地解决这两个问题.
良好的API描述和文档确实非常重要.成熟框架中REST和SOAP之间的区别主要在于几行配置.
对于SOAP,发送哈希作为SOAP安全性的一部分; 对于REST,我喜欢将所有内容打包在有效负载中,并避免HTTP头进行身份验证.我只有主观原因,因为我不得不与不容易暴露HTTP标头的框架作斗争.
我个人的偏好是针对不同的协议版本具有不同的URI.根据我的经验,这为新版本提供了更大的灵活性,连接到不受支持的协议版本的旧客户端会立即停止工作,原因很明显.此外,有时您可以将旧版本的应用程序映射到旧URI,以避免在新服务器版本中使用旧版支持代码.
至于你支持旧版协议的时间长短...理想情况下,只要你有使用它的客户端.这比技术决策更具商业性.您应该至少支持一个以前的协议版本.将客户推向新版本以降低传统支持成本通常符合您的利益; 从客户端来看,新版本应该意味着新功能,更好的协议以及某种额外的业务激励(如果仅仅新功能还不够).
您可能对Joshua Bloch的演讲"如何设计一个好的API及其重要性"感兴趣.Joshua Bloch是"Effective Java"的作者,也是Google的首席软件工程师和首席Java架构师.
摘要:http://portal.acm.org/citation.cfm？id = 1176622
幻灯片:http://lcsd05.cs.tamu.edu/slides/keynote.pdf
视频:http://www.youtube.com/watch？v = aAb7hSCtvGw
使用Content-Type标头进行REST版本控制的内容如下:http: //barelyenough.org/blog/2008/05/versioning-rest-web-services/
京公网安备 11010802040832号 | 京ICP备19059560号-6 
