48

在我的公司，我们开始涉足 Web API 以访问和更新我们的数据；最初是为合作伙伴提供的，但将来可能会向公众提供。目前 API 的外观（例如 SOAP、REST、RPC）是完全开放的，我们还没有做出任何决定，所以我对人们认为好的 Web API 的两个示例以及您认为的原因很感兴趣那。

我感兴趣的是来自使用不同语言的人的意见（我们可能会向使用多种平台的人提供 API，特别是包括 .NET、Java、ActionScript 和 JavaScript）关于您认为好的 Web API例子，你有很好的经验。

我想介绍的几点：

  1. 你更喜欢 SOAP 类型的服务还是 REST/RPC 风格的服务？我怀疑有平台支持（例如.NET、Java）的人会更喜欢SOAP，而使用没有平台支持的语言的人会更喜欢其他人，但我想验证这个假设。

  2. 您是否关心 API 是否实际上是 RESTful 或是否是普通的旧 RPC 样式 HTTP GET/POST？如果是这样，你为什么在乎？一个 API 是否正确地描述自己（即如果它是 RPC 风格就不要声称是 RESTful）比它是否实际上是两者之一更重要？

  3. 我们需要验证谁在使用该服务。我一直在研究 Amazon S3 身份验证，它使用公共标识符和私有令牌，用于将请求的参数散列为验证令牌（这也类似于 flickr）。您以前是否使用过这种类型的身份验证，您是如何使用它的？是否有任何您发现有问题的哈希算法（即您的平台不支持）？您希望在 HTTP 标头中还是在 URI 中发送散列？

  4. 应该如何处理版本控制？拥有一个类型子目录是一个好主意，/v1/以便可以在旁边添加未来的版本，还是你会做一些不同的事情，比如在请求有效负载或查询中使用版本？您期望支持您构建的 API 版本多长时间（即，如果引入 v2，您对 v1 生命周期的期望是多少）。

此外，任何其他意见和要点都会很有用。

我故意对我们正在实现的 API 的实际类型保持模糊，因为我正在寻找关于人们认为好的 API 和实现机制的一般指导，所以这篇文章及其答案将对更多人有用在将来。

注意：我已经搜索并找不到关于此的通用问题 - 它们似乎都特定于某种类型的 API - 但如果它是重复的，请告诉我。另外，如果它应该是社区 wiki（我认为人们应该得到答案，所以我没有做到这一点），那么请告诉我，我会改变它。

4

8 回答 8

19

这是我的看法。

  1. 尽管从 Java 的角度来看，我实际上更喜欢 REST。具有多个名称空间的 SOAP 信封及其复杂的结构令人厌恶。它试图解决大多数想象中的问题，但不能有效地解决任何问题。我发现 SOAP 唯一有用的是它具有授权和错误标准。另一方面，通过在根 XML 元素中包含四个标准属性（用户名、密码、errorCode、errorDescription）可以更轻松地解决这两个问题。

  2. 好的 API 描述和文档确实是最重要的。成熟框架中 REST 和 SOAP 的区别主要在于几行配置。

  3. 对于 SOAP，发送散列作为 SOAP 安全性的一部分；对于 REST，我喜欢将所有内容打包在有效负载中，并避免使用 HTTP 标头进行身份验证。不过，我只有主观原因，因为我不得不与那些不容易暴露 HTTP 标头的框架作斗争。

  4. 我个人的偏好是为不同的协议版本使用不同的 URI。根据我的经验，这为您在较新版本中提供了更大的灵活性，并且连接到不受支持的协议版本的旧客户端由于显而易见的原因而立即停止工作。此外，有时您可以将旧版本的应用程序映射到旧的 URI，以避免在新的服务器版本中有旧的支持代码。

    至于您支持旧版本协议的时间......理想情况下，只要您有使用它的客户端。这比技术决策更重要。您应该至少支持一个以前的协议版本。将客户推向新版本以降低遗留支持成本通常符合您的利益；从客户端来看，新版本应该意味着新功能、更好的协议和某种额外的业务激励（如果仅新功能还不够的话）。

于 2009-01-06T10:35:59.377 回答
9

您可能对 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

于 2009-01-06T07:27:05.047 回答
5

使用 Content-Type 标头的 REST 版本控制在这里很好地介绍了：http: //barelyenough.org/blog/2008/05/versioning-rest-web-services/

于 2009-01-04T12:18:46.707 回答
3

我会看看亚马逊在做什么 - http://aws.amazon.com/ - 从这些东西上赚钱的人显然会比其他人学到更多的教训。

我会看的其他 API - salesforce.com 和 Microsoft 的 CRM api 相当有趣。Twitter 也有一个久经沙场的 REST api。

于 2009-01-05T13:30:56.777 回答
3

RPC 方法也是一个不错的选择。它减少了开销，Ice、Google Protocol Buffers 和 Apache Thrift 等项目使开发基于 RPC 的服务变得更容易。

如果您不必提供基于 Web 的 API，那么 RPC 也可以是您想要探索的选择。

于 2010-09-02T06:58:41.313 回答
1

恕我直言，这完全取决于您提供的应用程序类型。如果您正在做重要的、大型的交易，那么一定要使用 SOAP（他们称之为 WS “死星”）。但是，如果您提供社交应用程序，那么请使用 REST，因为它更简单，更适合公共黑客攻击。

于 2009-01-03T22:12:41.517 回答
1

REST，如果做得正确，很容易理解（模型 HTTP），直接（面向资源）并且可以被几乎所有的编程语言 (XML) 解析。

于 2009-01-05T15:19:53.283 回答
0

如果您最终无法下定决心，则可以全部实施。在这些情况下，看看其他人是如何做到的很有用。我向您推荐 Open Source XML Native Database eXist，它提供了您正在研究的三种类型的接口。

于 2009-01-04T12:49:04.197 回答