我即将编写一份API，希望能找到一些关于如何编写优秀API和需要注意的问题的好建议。
当然，我已经通过谷歌搜索找到了Dustin Diaz的这篇文章http://www.dustindiaz.com/api-writing-tips/，但除此之外，我并没有找到其他好的建议。
在创建API时，有哪些事情让您希望能够采用不同的方法呢？哪些是最重要的因素？
我打算使用OAuth。
出于希望这些建议对更多人有用的考虑，我故意不提供API的详细信息。
编写API的建议
13
- pedalpete
1
2Joshua Bloch的一般API讲话：视频：http://www.youtube.com/watch?v=aAb7hSCtvGw / 幻灯片（PDF）：http://aarontgrogg.com/wp-content/uploads/2009/09/How-to-Build-API-and-why-it-matters.pdf - miku
4个回答
20
以下是我建议您关注的重点：
- 实现RESTful接口
- 提供多种数据格式（JSON、XML等）
- 使语法直观易懂
- 详尽的文档
- 使用正确的响应代码
此外，以下链接可能对您有所帮助：
http://www.slideshare.net/eaton/building-apis-that-rock
http://www.notiondesign.ca/blog/story/how-not-to-build-an-api/
http://blog.apigee.com/category/api_best_practices/
http://blog.isnotworking.com/2007/05/api-design-guidelines.html
此外，这本书可能会帮助您入门：
- Swift
1
我认为“语言无关”标签不适用于这个问题，而且它需要一个特定的语言标签。设计一个好的API需要考虑你正在使用的语言的特点和习惯用法。一些最重要的考虑因素：
- 内存是手动管理、使用RAII还是使用垃圾回收。
- 语言中是否支持泛型编程、面向对象编程、函数式编程等。
- 语言使用的类型系统是什么。
所以，我能给出的最好建议是，对于你提出的这个问题（语言无关），不要假设存在语言无关的通用API设计准则，而是要了解你正在使用的语言及其适当的习惯用法。
- R.. GitHub STOP HELPING ICE
2
2我将其重新标记为与语言无关。他正在谈论构建Web服务（因此提到oAuth），这通常与高级语言配对使用（http://oauth.net/code/）。我再次标记以反映这一点，抱歉混淆。 - Swift
谢谢 Mike，我以前从未见过那些“非技术”的标签。如果我再问类似的问题，我就会知道该如何使用它们了。 - pedalpete
0
- API必须清晰易懂 易于学习 即使没有文档也易于使用 难以误用 功能应该易于解释 名称应该基本上是自我解释的 名称应该一致：同一个词在整个API中应该表示相同的含义 API应该是规则的，具有一定的对称性
致谢
http://sharismlab.com/blog/2012/07/21/how-to-write-an-api-for-your-web-app/
- Kingsley Mitchell
0
了解用户将如何使用您的应用程序。如果您能够记录下应用程序的所有用例，则可以将每个用例作为 API 的一部分实现。最终，您将拥有一个提供您决定的一组用例的 API。此外，您应该能够通过扩展用例来扩展 API，并且应该能够维护向后兼容性。
Web服务的API实现： 确定您需要使用哪种协议、数据格式和身份验证。大多数 Web 服务都使用以下参数实现 API。
Web服务的API实现： 确定您需要使用哪种协议、数据格式和身份验证。大多数 Web 服务都使用以下参数实现 API。
Protocol: HTTP
Dataformat : JSON/XML
Authentication : API key/Oauth
库和SDK的API实现：
创建原型，应在整个生命周期内保持不变。
通过添加额外的函数来扩展API，而不更改现有函数的原型。
允许用户尽可能提供多个输入作为函数的参数。
这样应用程序可以按照用户的请求完成其工作。
考虑用户并使API允许用户以最少的努力使用它。
参考：
API简介：https://zapier.com/learn/apis
- Gangadhar
网页内容由stack overflow 提供, 点击上面的可以查看英文原文，
原文链接
原文链接