最好的 SOAP/REST/RPC Web API 示例?你为什么喜欢他们?他们怎么了? [英] Examples of the best SOAP/REST/RPC web APIs? And why do you like them? And what's wrong with them?
问题描述
在我的公司，我们开始涉足网络 API 以访问和更新我们的数据；最初面向合作伙伴，但未来可能面向公众.目前，API 的外观(例如 SOAP、REST、RPC)是完全开放的，我们还没有做出任何决定，所以我对人们认为很好的两个 Web API 示例感兴趣，以及您认为的原因
At my company we're starting to branch into web APIs to access and update our data; initially for partners but then likely to the public in future. At the moment the way the API will look (e.g. SOAP, REST, RPC) is completely open and we haven't made any decisions yet, so I'm interested in both examples of web APIs people think are good, and why you think that.
我感兴趣的是使用不同语言的人(我们很可能会向使用多种平台的人提供 API，特别是包括 .NET、Java、ActionScript 和 JavaScript)关于您使用的 Web API 的意见认为是很好的例子，并且你有很好的经验.
What I'm interested in is opinions from people using different languages (we're likely to be offering the API to people using a number of platforms, particularly including .NET, Java, ActionScript and JavaScript) about web APIs that you think are good examples, and that you've had good experiences with.
我想说的几点:
您更喜欢 SOAP 类型的服务还是 REST/RPC 风格的服务?我怀疑有平台支持(例如 .NET、Java)的人会更喜欢 SOAP，而使用没有平台支持的语言的人会更喜欢其他语言，但我想验证这个假设.
Do you prefer SOAP type services or REST/RPC style ones? I suspect that people with platform support (e.g. .NET, Java) will prefer SOAP ones and people using languages without platform support will prefer the others, but I'd like to validate that assumption.
您是否关心 API 是真正的 RESTful 还是普通的旧式 RPC 样式 HTTP GET/POST?如果是这样，你为什么要关心?一个 API 正确地描述自己(即如果它是 RPC 风格，不要声称是 RESTful)比它实际上是两者之一更重要吗?
Do you care whether an API is actually RESTful or whether it is a plain old RPC style HTTP GET/POST? If so, why do you care? Is it more important that an API describes itself correctly (i.e. don't claim to be RESTful if it's RPC style) than whether it actually is one of the two?
我们需要验证谁在使用该服务.我一直在研究 Amazon S3 身份验证，它使用公共标识符和私有令牌，用于将请求的参数散列到验证令牌中(这也类似于 flickr).您以前是否使用过这种类型的身份验证，您是如何使用它的?您是否发现任何散列算法有问题(即您的平台不支持)?您更愿意在 HTTP 标头中还是在 URI 中发送哈希?
We need to verify who is using the service. I've been looking at the Amazon S3 authentication which uses a public identifier and a private token that's used to hash the parameters of the request into a verification token (this is also similar to flickr). Have you used this type of authentication before, and how did you get on with it? Are there any hash algorithms you find problematic (i.e. not supported by your platform)? Would you prefer to send the hash in an HTTP header or in the URI?
应该如何处理版本控制?拥有一个 /v1/ 类型的子目录是否是个好主意，以便将来的版本可以添加到一起，或者您是否会做一些不同的事情，例如在请求有效负载或查询中包含版本?您希望针对您构建的 API 版本支持多长时间(即，如果引入了 v2，您对 v1 的生命周期的期望是多少).
How should versioning be handled? Is it a good idea to have a /v1/ type subdirectory so that future versions can be added alongside, or would you do something differently like have the version in the request payload or query? How long would you expect a version of an API that you'd built against to be supported for (i.e. if v2 was introducted, what would be your expectancy around the lifetime of v1).
此外，要涵盖的任何其他意见和要点都会有所帮助.
Also, any other opinions and points to cover would be useful.
我故意对我们正在实施的 API 的实际类型保持含糊，因为我正在寻找关于人们认为好的 API 和实施机制的一般指导，因此这篇文章及其答案将很有用未来更多的人.
I'm deliberately staying vague on the actual type of API we're implementing, as I'm looking for general guidance in terms of what people think are good APIs and implementation mechanisms, so this post and its answers will be useful to more people in the future.
注意:我已经搜索过但找不到关于此的通用问题 - 它们似乎都特定于某种类型的 API - 但如果它是重复的，请告诉我.另外，如果它应该是社区 wiki(我认为人们应该为答案赢得赞誉，所以我没有做到)，那么请告诉我，我会改成这样.
推荐答案
这是我的看法.
虽然从 Java 的角度来看，我实际上更喜欢 REST.具有多个名称空间的 SOAP 信封及其复杂的结构令人讨厌.它试图解决大部分想象中的问题，并没有有效地解决任何问题.我发现 SOAP 唯一有用的是它具有授权和错误的标准.另一方面，通过在根 XML 元素中包含四个标准属性(用户名、密码、errorCode、errorDescription)，可以更轻松地解决这两个问题.
Although coming from a Java standpoint, I actually prefer REST. SOAP envelope with multiple namespaces and its complex structure is abomination. It tries to solve mostly imaginary problems, and doesn't solve anything efficiently. Only thing about SOAP I've found useful is that it has standards for authorization and errors. On the other hand, both could be solved much easier by including four standard attributes in root XML element - username, password, errorCode, errorDescription.
好的 API 描述和文档确实很重要.成熟框架中 REST 和 SOAP 的区别主要在于几行配置.
Good API description and documentation is indeed all that matters. Difference between REST and SOAP in mature framework is mostly in a few lines of configuration.
对于 SOAP，发送哈希作为 SOAP 安全性的一部分；对于 REST，我喜欢将所有内容打包在有效负载中，并避免使用 HTTP 标头进行身份验证.不过，我只有主观原因，因为我不得不与不容易暴露 HTTP 标头的框架作斗争.
For SOAP, send hash as part of SOAP security; for REST, I like to package everything in payload and avoid HTTP headers for authentication. I have only subjective reasons though, since I had to battle with frameworks which don't easily expose HTTP headers.
我个人的偏好是针对不同的协议版本使用不同的 URI.根据我的经验，这在新版本中为您提供了更大的灵活性，并且连接到不受支持的协议版本的旧客户端会立即停止工作，原因很明显.此外，有时您可以将旧版本的应用程序映射到旧 URI，以避免在新服务器版本中具有遗留支持代码.
至于您支持旧版本协议的时间......理想情况下，只要因为您有使用它的客户.这与其说是技术决策，不如说是商业决策.您应该至少支持一个以前的协议版本.将客户推向新版本以降低传统支持成本通常符合您的利益；从客户端来看，新版本应该意味着新功能、更好的协议和某种额外的业务激励(如果仅靠新功能还不够).
My personal preference is having different URIs for different protocol versions. In my experience, this gives you more flexibility in newer versions, and old clients which connect to unsupported versions of a protocol stop working immediately and for obvious reasons. Also, sometimes you can map old version of application to old URI, to avoid having legacy support code in new server version.
As for how long you support old version of protocol... ideally, as long as you have clients which use it. This is more business than technical decision. You should support at least one previous protocol version. It's usually in your interest to push clients towards new version to lower legacy support costs; from the clients side, new version should mean new features, better protocol, and some sort of additional business incentive (if new features alone are not enough).
这篇关于最好的 SOAP/REST/RPC Web API 示例?你为什么喜欢他们?他们怎么了?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！
