Having worked with a few, I'll get right down to it
Facebook
GOOD: clean and relatively consistent. Performs well and most things logically make sense. FQL is pretty neat. XML and JSON options. No pre-conception of response format other than what you really need
BAD: Changes often and without warning. 'official' api libraries are pretty atrocious. documentation of many calls are poor or missing. Non-standard authentication (some may call this good?)
Myspace
GOOD: open standards (oAuth authentication, Opensocial endpoint)
BAD: often broken. Usage of oauth is very nonstandard and breaks most client libraries. official client libraries are terrible.
Photobucket (disclaimer: I wrote the server side of the photobucket api)
GOOD: open standard authentication (oauth). xml, json, even php serialized array format as response parameters. faithful REST (get/put/delete/post on 'noun' urls).
BAD: not many client libraries. Architectural challenges with standard oauth libraries (users live on subdomains, calls must be made to subdomain, so url has to change).
Twitter
GOOD: pretty consistent (though api vs search api has diffs). Good REST practice. OAuth authentication as well as supporting oldschool Basic.
BAD: error rate (pretty much consistent with rest of twitter though). Odd format of some return values (like their date format).
Ideal characteristics
I'm not sold on 'strict' REST. PUT and DELETE cause problems in some client languages. GET and POST seem to be sufficient with appropriate 'verbs'. Also, RPC-like function names are OK with me as long as they're logical and maybe even part of the URI. In that case, object IDS still need to be very consistent though.
Standard authentication/authorization. Basic/Digest can be ok, but I'm a fan of OpenID/oAuth (or WRAP if you want to get bleeding edge). Rolling your own means you have to explain 100% of it, and potentially write client libraries for everyone.
Standard datatypes. Make sure you are consistent about your datatypes (either 'true' or 1, not some mix), and support the most generic standards. Datetime should be ISO8601. Geolocation should 'look like' GeoRSS, etc. You should be able to create an XSD/relaxNG/whatever strict validator for your return types. Expect the same standards from your inputs.
Simple return structure. there's some benefit to XML-RPC/JSON-RPC in that you kinda know what you're getting back, but in any case, if I cant easily parse your return type with JSON or something like PHP's SimpleXML and essentially serialize it to a consistent hash, I'm going to be pissed.
Support extension/expansion without breakage. Dont code yourself into a corner and make it hard to add to your API. Try to make good decisions up front that you wont be changing constantly.
Documentation! Make sure its good, and explains everything. Even then it won't be good enough, so make sure you have dedicated time to work on it and a supporting forum or whatever to keep it up to date.
So that being said... something between Facebook and Twitter. Of course I'm partial to some of the stuff we have on Photobucket, but I also hate some of it.
It would seem to me that the documentation of the API is just as (or more) important than the actual design of the API.
Well written, simple documentation will make up for any design flaws. That's what I've learned after looking at the various links posted already. Specifically, Last.fm's documentation seems very good: easy to navigate and easy to understand.
Last.fm's api continues to be one of the most well maintained apis on the net. It's also been around longer than most, because it started out basically as just that.
I would check out OpenSocial, a movement to create an API Standard for social network sices. They use REST for this and have a 'user' centric approach. But this is a very well documented approach which might help for even a site that is not totally Social based. If you are looking for some internal code implementations look at Drupals hook system and Wordpress.
分层 API 集。 当 API 整齐地分层时，广泛的开发人员可以使用他们需要的部分，而无需引入无关的层。 作为一个优点，它迫使创建者认真思考干净和组件化的 API。
请在评论中添加更多内容。
I think the best way to answer is to list the characteristics of good web APIs instead of citing examples. If you like Twitter/Facebook/etc APIs, what aspect of these APIs do you find attractive?
I'll take a first stab:
Well documented APIs, including constraints and usage policies. This enables rapid development with confidence, instead of second guessing what the parameters might mean, and what return values are.
Technology/language agnostic APIs. Good APIs should be easily usable, providing the same functionality, across a wide array of languages and platforms.
Well supported APIs. There are always bugs. Responsive maintainers result in more usable APIs
Layered API sets. When APIs are neatly layered, a wide range of developers can consume the pieces they need without needing to pull in extraneous layers. As a plus, it forces the creators to think hard about clean and componentized APIs.
我对其他 API 没有任何经验，但即使它已经发展了多年，Facebook API 仍然很糟糕。 它远没有成为“黄金标准”。 相反，这是人们努力克服并咬紧牙关的事情，因为一旦他们最终做好了，它可以增加很多价值。
I don't have any experience with the others, but even as it has evolved over the years, the Facebook API is still awful. It doesn't come anywhere near being a "gold standard." Rather, it is something people struggle through and grit their teeth because once they finally get it right, it can add a lot of value.
这将取决于您的目标受众是什么。 如果是 .net 商店，那么肥皂可能还可以，否则专注于 REST，因为它的进入门槛要低得多。 从那里查看针对您想要的相同人群的网站 API。 这样你的 api 就会感觉很熟悉。
It will depend on what your target audience is. If it is .net shops then soap is probably okay other wise focus on REST since it has a much lower bar of entry. From there look at website APIs that target the same people you would like to. This way your api will feel familiar.
AtomPub is the gold standard because it was designed by some of the brightest minds on the internet. You can't go too far wrong using iit as a basis. That is what google and msft does.
设计 Web API 实际上与设计网站没有什么不同，除了您提供的内容将由非 Web 浏览器的程序使用。
您不想做的是创建基于 Http 的数据访问层。 这就像向世界展示你的内衣一样。 现有网站针对所有常见使用场景进行了优化，许多 api 访问模式将是相似的，因此请重用已创建的“视图”。 可能需要在这里或那里添加一些额外的链接，以使程序更快地获取所需的数据，但这些链接可以根据需要逐步添加。
编写良好的网站对于 Web 浏览器客户端来说已经是非常有效的 API，实际上没有必要重新设计来支持任何其他类型的客户端。 API结构不需要改变，只需要改变交付的内容。
If I were designing a web api today for an existing web site, assuming the web site was well designed with respect to its proper usage of HTTP, I would use the existing web site as the design guideline.
Take Stack Overflow as an example, it has the entire URI space already mapped out. It has a complete set of interconnections defined between the different representations. Users of the site are already familiar with the site structure and therefore the API structure would already be familiar.
The only part that needs to change is the content of the representations, to eliminate all unnecessary markup. It would be necessary to add in a few extra templated links to allow for searches that are currently only accessible via javascript. For example, searching for a user is not easily discoverable via navigating because currently the link is built via javascript.
The really tricky decision is what media-type to use. You could use bare bones html with RDFa style metadata markup, or go wild and use the new Microdata format in Html5. Or, you could return a custom media type based on xml or Json. Something like application/vnd.stackoverflow.question+xml, etc. The custom media type makes versioning really easy, but it is less accessible to clients that were not designed to access StackOverflow directly. The custom types could be used in combination with Atom feeds which are mostly already there in StackOverflow,
Designing a web api is really no different than designing a website, other than the fact that you are delivering content that will be consumed by a program that is not a web browser.
What you don't want to do is create an Http based data access layer. That is just like showing your underwear to the world. The existing web site is optimized for all the common usage scenarios, many of the api access patterns are going to be similar, so reuse the "views" that have already been created. It may be necessary to add a few extra links here and there to make it a bit quicker for programs to get the data they want, but those can be added incrementally as the need arises.
Well written web sites are already very effective APIs for web browser clients, it is really not necessary to go back to the drawing board to support any other type of client. The API structure does not need to change, just the delivered content.
发布评论
评论（15）
我们自己也在这方面做一些研究。 网站 API 参考的“黄金标准”并不多。
最常见的网站 API 引用有：
这里的另一个列表：
http:// /www.pingable.org/the-top-15-web-apis-for-your-site/
有人推荐了这本书Restful Web Services 作为这方面的一个很好的参考。
（请随意编辑上面的列表以添加其他具有 API 的知名网站）
We're doing some research in this area ourselves. Not a lot out there in terms of "gold standard" for website API references.
The most common website APIs referenced are:
Another list here:
http://www.pingable.org/the-top-15-web-apis-for-your-site/
Someone recommended the book Restful Web Services as a good reference on this.
(please feel free to edit the above list to add other high profile websites with APIs)
如何设计良好的 API 及其重要性，由 < 主持的 60 分钟 Google 技术讲座a href="http://en.wikipedia.org/wiki/Joshua_Bloch" rel="noreferrer">Joshua Bloch 是相关的。
How To Design A Good API and Why it Matters, a 60 minute Google tech talk by Joshua Bloch, is relevant.
与一些人合作后，我会立即着手
Facebook
Myspace
Photobucket（免责声明：我编写了 photobucket api 的服务器端）
推特
理想的特征
话虽这么说……Facebook 和 Twitter 之间的某种东西。 当然，我偏爱 Photobucket 上的一些内容，但我也讨厌其中的一些内容。
Having worked with a few, I'll get right down to it
Facebook
Myspace
Photobucket (disclaimer: I wrote the server side of the photobucket api)
Twitter
Ideal characteristics
So that being said... something between Facebook and Twitter. Of course I'm partial to some of the stuff we have on Photobucket, but I also hate some of it.
在我看来，API 的文档与 API 的实际设计一样（或更重要）重要。
写得好的、简单的文档将弥补任何设计缺陷。 这就是我在查看已经发布的各种链接后了解到的内容。 具体来说，Last.fm 的文档看起来非常好：易于导航且易于理解。
It would seem to me that the documentation of the API is just as (or more) important than the actual design of the API.
Well written, simple documentation will make up for any design flaws. That's what I've learned after looking at the various links posted already. Specifically, Last.fm's documentation seems very good: easy to navigate and easy to understand.
Last.fm 的 api 仍然是网络上维护得最好的 api 之一。 它的存在时间也比大多数产品都要长，因为它一开始基本上就是这样。
http://www.last.fm/api
Last.fm's api continues to be one of the most well maintained apis on the net. It's also been around longer than most, because it started out basically as just that.
http://www.last.fm/api
关于 Jeff 的大型 API 列表：我非常确定commonnot意味着“黄金标准”。
无需保留广泛使用的 API 的手动列表。 要获取列表，请查看 http://www.programmableweb.com/apis/目录/1?sort=mashups 。
由于我喜欢 REST 作为宽松的标准，因此当 API 有意义且直观时，我会说 API 是“黄金”。
...所有这些对我来说最有意义并且经过深思熟虑（正如布莱恩已经指出的那样）。
在我目前的日常工作中，我也经常使用 OpenSocial，其中 URI 感觉非常自然，而且还以自己的方式扩展了 REST 标准。
如果您喜欢严格且安全，请使用 SOAP。
Regarding Jeff's list of big APIs: I am pretty sure that common does not mean "Gold Standard".
No need to keep a manual list of widespread API. To get a list check out http://www.programmableweb.com/apis/directory/1?sort=mashups .
Since I like REST as loose standard, I'd say that an API is "Golden" when it makes sense and is intuitive.
… all make the most sense for me and are well thought out (as Brian already pointed out).
In my current daily work I also work a lot with OpenSocial, where URIs feel very natural but also extend the REST standard in its own way.
If you like it strict and safe, use SOAP.
我会查看 OpenSocial，这是一项为社交网络服务创建 API 标准的运动。 他们为此使用 REST，并采用以“用户”为中心的方法。 但这是一种有据可查的方法，即使对于不完全基于社交的网站也可能有所帮助。 如果您正在寻找一些内部代码实现，请查看 Drupals 挂钩系统和 Wordpress。
http://code.google.com/apis/opensocial/
I would check out OpenSocial, a movement to create an API Standard for social network sices. They use REST for this and have a 'user' centric approach. But this is a very well documented approach which might help for even a site that is not totally Social based. If you are looking for some internal code implementations look at Drupals hook system and Wordpress.
http://code.google.com/apis/opensocial/
我认为最好的回答方法是列出优秀 Web API 的特征，而不是引用示例。 如果您喜欢 Twitter/Facebook/等 API，您认为这些 API 的哪些方面有吸引力？
我将首先尝试：
请在评论中添加更多内容。
I think the best way to answer is to list the characteristics of good web APIs instead of citing examples. If you like Twitter/Facebook/etc APIs, what aspect of these APIs do you find attractive?
I'll take a first stab:
Please add more to comments.
我对其他 API 没有任何经验，但即使它已经发展了多年，Facebook API 仍然很糟糕。 它远没有成为“黄金标准”。 相反，这是人们努力克服并咬紧牙关的事情，因为一旦他们最终做好了，它可以增加很多价值。
I don't have any experience with the others, but even as it has evolved over the years, the Facebook API is still awful. It doesn't come anywhere near being a "gold standard." Rather, it is something people struggle through and grit their teeth because once they finally get it right, it can add a lot of value.
一些特别好的 API：
Some APIs which are notably good:
这将取决于您的目标受众是什么。 如果是 .net 商店，那么肥皂可能还可以，否则专注于 REST，因为它的进入门槛要低得多。
从那里查看针对您想要的相同人群的网站 API。 这样你的 api 就会感觉很熟悉。
It will depend on what your target audience is. If it is .net shops then soap is probably okay other wise focus on REST since it has a much lower bar of entry.
From there look at website APIs that target the same people you would like to. This way your api will feel familiar.
Force（以前称为 SalesForce）API：http://www.salesforce .com/us/developer/docs/api/index.htm
Force (previously known as SalesForce) API: http://www.salesforce.com/us/developer/docs/api/index.htm
AtomPub 是黄金标准，因为它是由互联网上一些最聪明的人设计的。 使用 iit 作为基础不会走得太远。 这就是谷歌和微软所做的。
AtomPub is the gold standard because it was designed by some of the brightest minds on the internet. You can't go too far wrong using iit as a basis. That is what google and msft does.
有一个与此类似的问题，但没有得到太多行动，但认为链接到它会很好。
Web API 会做什么您最想复制或最受欢迎？
Had a similar question to this which didn't get much action, but thought it would be good to link to it.
What web APIs would you most want to replicate or are the most popular?
如果我今天为现有网站设计 Web API，假设该网站在正确使用 HTTP 方面设计得很好，我会使用现有网站作为设计指南。
以 Stack Overflow 为例，它已经映射了整个 URI 空间。 它具有在不同表示之间定义的完整互连集。 网站的用户已经熟悉网站结构，因此 API 结构也已经熟悉。
唯一需要更改的部分是表示的内容，以消除所有不必要的标记。 有必要添加一些额外的模板化链接，以允许当前只能通过 JavaScript 访问的搜索。 例如，通过导航不容易发现搜索用户，因为当前链接是通过 JavaScript 构建的。
真正棘手的决定是使用哪种媒体类型。 您可以使用带有 RDFa 样式元数据标记的基本 html，或者疯狂地使用 Html5 中的新 Microdata 格式。 或者，您可以返回基于 xml 或 Json 的自定义媒体类型。 像 application/vnd.stackoverflow.question+xml 之类的东西。自定义媒体类型使版本控制变得非常容易，但对于并非设计为直接访问 StackOverflow 的客户端来说不太容易访问。 自定义类型可以与 Atom feeds 结合使用，Atom feeds 大多数已经存在于 StackOverflow 中，
设计 Web API 实际上与设计网站没有什么不同，除了您提供的内容将由非 Web 浏览器的程序使用。
您不想做的是创建基于 Http 的数据访问层。 这就像向世界展示你的内衣一样。 现有网站针对所有常见使用场景进行了优化，许多 api 访问模式将是相似的，因此请重用已创建的“视图”。 可能需要在这里或那里添加一些额外的链接，以使程序更快地获取所需的数据，但这些链接可以根据需要逐步添加。
编写良好的网站对于 Web 浏览器客户端来说已经是非常有效的 API，实际上没有必要重新设计来支持任何其他类型的客户端。 API结构不需要改变，只需要改变交付的内容。
If I were designing a web api today for an existing web site, assuming the web site was well designed with respect to its proper usage of HTTP, I would use the existing web site as the design guideline.
Take Stack Overflow as an example, it has the entire URI space already mapped out. It has a complete set of interconnections defined between the different representations. Users of the site are already familiar with the site structure and therefore the API structure would already be familiar.
The only part that needs to change is the content of the representations, to eliminate all unnecessary markup. It would be necessary to add in a few extra templated links to allow for searches that are currently only accessible via javascript. For example, searching for a user is not easily discoverable via navigating because currently the link is built via javascript.
The really tricky decision is what media-type to use. You could use bare bones html with RDFa style metadata markup, or go wild and use the new Microdata format in Html5. Or, you could return a custom media type based on xml or Json. Something like application/vnd.stackoverflow.question+xml, etc. The custom media type makes versioning really easy, but it is less accessible to clients that were not designed to access StackOverflow directly. The custom types could be used in combination with Atom feeds which are mostly already there in StackOverflow,
Designing a web api is really no different than designing a website, other than the fact that you are delivering content that will be consumed by a program that is not a web browser.
What you don't want to do is create an Http based data access layer. That is just like showing your underwear to the world. The existing web site is optimized for all the common usage scenarios, many of the api access patterns are going to be similar, so reuse the "views" that have already been created. It may be necessary to add a few extra links here and there to make it a bit quicker for programs to get the data they want, but those can be added incrementally as the need arises.
Well written web sites are already very effective APIs for web browser clients, it is really not necessary to go back to the drawing board to support any other type of client. The API structure does not need to change, just the delivered content.