网站 API 的黄金标准是什么？ Twitter、Flickr、Facebook 等 [关闭]答案

【问题标题】：What is the gold standard for website APIs? Twitter, Flickr, Facebook, etc [closed]网站 API 的黄金标准是什么？ Twitter、Flickr、Facebook 等 [关闭]
【发布时间】：2008-11-17 21:28:22
【问题描述】：

今天的网站似乎有两类 API。

允许扩展网站功能的 API，如 Facebook、Myspace 等。这些 API 似乎非常多样化。
允许与现有网站功能（如 Twitter、Flickr 等）进行交互的 API。这些都声称基于 REST，但实际上只是“HTTP 上的数据”。

如果您正在创建一个允许功能扩展和外部交互的网站，您会使用哪些现有 API 作为参考模型？

【问题讨论】：

条纹效果在 3... 2... 1...
@Charlie “史翠珊效应主要是一种在线现象，在这种现象中，试图审查或删除一条信息的行为会产生意想不到的后果，导致该信息被广泛宣传，并且在更大程度上如果没有尝试过审查，就会发生……”对不起，我不明白？
更好的问题是“好的 Web API 有哪些特征？”。我认为这就是你想要达到的目的。或者这就是你应该想要达到的。我试图回答，如下。
@Pongus 嗯，够近了。我说的是 Jeff 在 Twitter 上发布这个问题，引起了他的大量投票。这不完全是史翠珊效应，但它有相同的 jist
@Charlie Somerville，和你一起！可能更多的是 Katie Price 效应... :o)

标签： rest api-design asp.net-web-api

【解决方案1】：

我们自己也在这方面做一些研究。网站 API 参考的“黄金标准”并不多。

引用的最常见的网站 API 是：

Google API http://developers.google.com/api-client-library/java/apis
亚马逊 S3 http://docs.amazonwebservices.com/AmazonS3/latest/API/
推特https://dev.twitter.com/
脸书http://developers.facebook.com/
领英http://developer.linkedin.com/index.jspa
好吃http://delicious.com/help/api
YouTube http://www.youtube.com/dev
Netflix http://developer.netflix.com/
太阳云 API http://kenai.com/projects/suncloudapis/pages/Home

这里的另一个列表：

http://www.pingable.org/the-top-15-web-apis-for-your-site/

有人推荐这本书Restful Web Services 作为这方面的一个很好的参考。

（请随时编辑以上列表以添加其他具有 API 的知名网站）

【讨论】：

+5。现在我在说什么关于史翠珊效应？ :P
-1 虽然这些可能是“流行”的 API，但其中许多绝对不是“黄金标准”。例如，Flickr API 特别有趣。它宣称自己是 RESTful 的，但它什么都不是！
@nathan 看到哪里写着“请随意编辑”？嗯..请随意！只需点击编辑链接！
我也对这个话题感兴趣。我最近发现了 Mashery - 他们似乎在您面向公众的 API 之上添加了一个层，这有助于限制权限和用户的请求。
Sun Cloud API 是迄今为止最接近 REST 风格的 API。

【解决方案2】：

How To Design A Good API and Why it Matters，Joshua Bloch 的 60 分钟 Google 技术讲座，具有相关性。

【讨论】：

【解决方案3】：

与一些人合作过，我会直接开始的

脸书
- 良好：干净且相对一致。表现良好，大多数事情在逻辑上都是有意义的。 FQL 非常简洁。 XML 和 JSON 选项。除了您真正需要的以外，没有任何响应格式的预先概念
- 错误：经常更改且没有警告。 “官方” api 库非常糟糕。许多电话的文档很差或丢失。非标准身份验证（有些人可能会认为这很好？）
我的空间
- 好：开放标准（oAuth 身份验证、Opensocial 端点）
- 坏：经常坏。 oauth 的使用非常不标准，并且会破坏大多数客户端库。官方客户端库很糟糕。
Photobucket（免责声明：我写了photobucket api的服务器端）
- GOOD：开放标准身份验证 (oauth)。 xml、json、甚至php序列化数组格式作为响应参数。忠实的 REST（在“名词”网址上获取/放置/删除/发布）。
- 错误：客户端库不多。标准 oauth 库的架构挑战（用户生活在子域中，必须对子域进行调用，因此 url 必须更改）。
推特
- GOOD：非常一致（尽管 api 与搜索 api 有差异）。良好的 REST 实践。 OAuth 身份验证以及支持 oldschool Basic。
- BAD：错误率（不过与 Twitter 的其余部分几乎一致）。一些返回值的奇怪格式（例如它们的日期格式）。

理想特征

我不喜欢“严格”的 REST。 PUT 和 DELETE 会导致某些客户端语言出现问题。使用适当的“动词”，GET 和 POST 似乎就足够了。此外，类似 RPC 的函数名称对我来说是可以的，只要它们是合乎逻辑的，甚至可能是 URI 的一部分。在这种情况下，对象 IDS 仍然需要非常一致。
标准认证/授权。 Basic/Digest 可以，但我是 OpenID/oAuth 的粉丝（或者如果你想获得最前沿的 WRAP）。滚动您自己意味着您必须 100% 解释其中的内容，并可能为每个人编写客户端库。
标准数据类型。确保您的数据类型保持一致（“真”或 1，而不是混合），并支持最通用的标准。日期时间应为 ISO8601。地理位置应该“看起来像”GeoRSS 等。您应该能够为您的返回类型创建一个 XSD/relaxNG/任何严格的验证器。期望您的输入具有相同的标准。
简单的返回结构。 XML-RPC/JSON-RPC 有一些好处，因为你有点知道你得到了什么，但无论如何，如果我不能用 JSON 或 PHP 的 SimpleXML 之类的东西轻松解析你的返回类型，并基本上将它序列化为一致哈希，我要生气了。
支持无破损扩展/扩展。不要将自己编码到一个角落，并使其难以添加到您的 API。尝试提前做出不会不断变化的正确决定。
文档！确保它是好的，并解释一切。即使那样它也不够好，所以请确保您有专门的时间来处理它，并有一个支持论坛或其他任何东西来保持它的最新状态。

这么说……Facebook 和 Twitter 之间的东西。当然，我偏爱 Photobucket 上的一些内容，但我也讨厌其中的一些内容。

【讨论】：

Twitter 上的一条评论“良好的 REST 实践”。 Twitter 不使用超媒体来发现链接，并且由于它使用通用媒体类型，因此响应不是自我描述的。它远非 RESTful。
@Darrel - 同意，但纯 RESTFUL 服务只有在机器人使用和更新时才是必要的 - 否则你会花太多时间担心 RESTful 而不是交付产品 IMO
@schmoopy 大多数静态 HTML 网站都是纯 RESTful 服务。那些只有机器人消耗吗？
@Darrel - 是的，只有谷歌阅读它们，我们阅读谷歌 ;-) - 我唯一的观点是纯粹的宁静可能并不理想，因为您的 API 是由开发人员而不是机器人使用的 -通常 - 如果网站要求用户使用解码器环来阅读它们，那么我确信网络会朝着不同的方向发展。

【解决方案4】：

在我看来，API 的文档与 API 的实际设计一样（或更多）重要。

写得好，简单的文档将弥补任何设计缺陷。这就是我在查看已经发布的各种链接后所学到的。具体来说，Last.fm 的文档看起来非常好：易于浏览且易于理解。

【讨论】：

【解决方案5】：

Last.fm 的 api 仍然是网络上维护最完善的 api 之一。它的存在时间也比大多数都长，因为它基本上就是这样开始的。

http://www.last.fm/api

【讨论】：

从我嘴里说出来的话 :)
尽管看起来不像 RESTful。所以在那里丢分很多。
是的，只是检查它以供参考，但我不能认真对待，因为我可以传入无效的方法路由并仍然返回 200 ResponseCode - ws.audioscrobbler.com/2.0/… 返回 200 的 HttpStatusCode - 应该是 404，因为它不是找到的“资源”IMO

【解决方案6】：

关于 Jeff 的大型 API 列表：我很确定 common 确实不意味着 “黄金标准”。

无需手动列出广泛使用的 API。要获取列表，请查看http://www.programmableweb.com/apis/directory/1?sort=mashups。

由于我喜欢将 REST 作为松散的标准，我会说 API 在有意义并且直观时是“黄金”。

……所有这些对我来说都是最有意义的，并且经过深思熟虑（正如 Brian 已经指出的那样）。

在我目前的日常工作中，我还经常使用 OpenSocial，其中 URI 感觉非常自然，但也以自己的方式扩展了 REST 标准。

如果您喜欢它严格和安全，请使用 SOAP。

【讨论】：

肥皂？对不起，我过去吐了……

【解决方案7】：

我会查看 OpenSocial，这是一项为社交网络创建 API 标准的运动。他们为此使用 REST，并采用以“用户”为中心的方法。但这是一个非常有据可查的方法，即使是不完全基于社交的网站也可能有所帮助。如果您正在寻找一些内部代码实现，请查看 Drupals 挂钩系统和 Wordpress。

http://code.google.com/apis/opensocial/

【讨论】：

【解决方案8】：

我认为最好的回答方式是列出优秀 Web API 的特征，而不是引用示例。如果您喜欢 Twitter/Facebook/etc API，您觉得这些 API 的哪些方面具有吸引力？

我会先试一试：

记录良好的 API，包括约束和使用策略。这样可以放心地进行快速开发，而不必再猜测参数可能意味着什么以及返回值是什么。
与技术/语言无关的 API。好的 API 应该易于使用，提供相同的功能，跨多种语言和平台。
支持良好的 API。总是有错误。响应迅速的维护者带来更多可用的 API
分层 API 集。当 API 被整齐地分层时，广泛的开发人员可以使用他们需要的部分，而无需引入无关的层。此外，它还迫使创作者认真思考干净和组件化的 API。

请向 cmets 添加更多内容。

【讨论】：

【解决方案9】：

我对其他人没有任何经验，但即使经过多年的发展，Facebook API 仍然很糟糕。它远非“黄金标准”。相反，这是人们努力克服并咬紧牙关的事情，因为一旦他们最终做对了，它可以增加很多价值。

【讨论】：

【解决方案10】：

一些非常好的 API：

Last.FM http://www.last.fm/api（精彩文档）
Github http://develop.github.com/（合作愉快，经过深思熟虑）

【讨论】：

【解决方案11】：

这将取决于您的目标受众是什么。如果是.net 商店，那么soap 可能还可以，否则明智地专注于REST，因为它的进入门槛要低得多。从那里查看针对您想要的相同人群的网站 API。这样你的 api 会感觉很熟悉。

【讨论】：

【解决方案12】：

Force（以前称为 SalesForce）API：http://www.salesforce.com/us/developer/docs/api/index.htm

【讨论】：

【解决方案13】：

AtomPub 是黄金标准，因为它是由互联网上一些最聪明的人设计的。使用 iit 作为基础，你不会走得太远。这就是 google 和 msft 所做的。

【讨论】：

【解决方案14】：

有一个与此类似的问题，但没有采取太多行动，但认为链接到它会很好。

What web APIs would you most want to replicate or are the most popular?

【讨论】：

【解决方案15】：

如果我今天为现有网站设计 Web api，假设网站在正确使用 HTTP 方面设计得很好，我会使用现有网站作为设计指南。

以 Stack Overflow 为例，它有整个 URI 空间已经映射出来。它在不同的表示之间定义了一套完整的互连。 网站的用户已经熟悉网站结构，因此 API 结构已经很熟悉了。

唯一需要更改的是表示的内容，以消除所有不必要的标记。有必要添加一些额外的模板链接，以允许当前只能通过 javascript 访问的搜索。例如，搜索用户不容易通过导航发现，因为当前链接是通过 javascript 构建的。

真正棘手的决定是使用什么媒体类型。您可以使用带有 RDFa 样式元数据标记的简单 html，或者在 Html5 中使用新的 Microdata 格式。或者，您可以返回基于 xml 或 Json 的自定义媒体类型。像 application/vnd.stackoverflow.question+xml 等。自定义媒体类型使版本控制变得非常容易，但对于不是设计为直接访问 StackOverflow 的客户端来说，它不太容易访问。自定义类型可以与 StackOverflow 中大部分已经存在的 Atom 提要结合使用，

设计 Web api 与设计网站实际上没有什么不同，除了您提供的内容将由非 Web 浏览器的程序使用。

你不想做的是创建一个基于 Http 的数据访问层。这就像向世界展示你的内衣一样。现有网站针对所有常见使用场景进行了优化，许多 api 访问模式将是相似的，因此重用已经创建的“视图”。可能需要在这里和那里添加一些额外的链接，以使程序更快地获取所需的数据，但可以根据需要逐步添加。

编写良好的网站对于网络浏览器客户端来说已经是非常有效的 API，实际上没有必要回到绘图板上来支持任何其他类型的客户端。 API 结构不需要改变，只需要改变交付的内容。

【讨论】：