Question

我即将写一个api，并认为我会找到一些关于要注意的事情的好建议，如何写一个好的api。

我当然做过Google搜索，但除了Dustin Diaz http://www.dustindiaz.com/api-writing-tips/之外，我还没有找到好的建议。

在创建API时，您希望您做了哪些不同的事情？是什么造成了最大的不同。

我假设我要使用oauth。

我故意不提供api的详细信息，因为我正在寻找更多一般性的建议，希望对更多人有用。

Answer 1

我建议你看一下关键点：

实施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

此外，这本书可以帮助您入门：

http://www.amazon.com/dp/0596529260/

Answer 2

我不认为与语言无关的标记适用于此问题，而且，它需要特定的语言标记。设计一个好的API需要考虑你正在使用的语言的特征和习语。一些最重要的考虑因素：

是使用RAII手动管理内存还是使用垃圾回收管理内存。
支持语言中的泛型编程，面向对象编程，函数式编程等。
语言使用的是什么类型的系统。

因此，我可以为您的问题提供的最佳建议（语言无关）不是假设存在与语言无关的通用API设计指南，而是了解您所使用的语言使用和适当的习语。

Answer 3

API必须清楚简单易学易于使用，即使没有文档难以滥用功能应该很容易解释名称应该在很大程度上不言自明名称应该是一致的：在整个API中，相同的单词应该表示相同的内容 API应该是规则的，有一些对称性

给予

http://sharismlab.com/blog/2012/07/21/how-to-write-an-api-for-your-web-app/

Answer 4

了解用户将如何使用您的应用程序。如果您能够记下应用程序的所有用例，那么您可以将每个用例实现为API的一部分。在一天结束时，您将拥有一个API，它提供您决定使用的一组用例。此外，您应该能够通过扩展用例来扩展API，并且应该能够保持向后兼容性。

Web服务的API实现：
确定您需要使用哪种协议，数据格式和身份验证大多数Web服务使用以下参数实现API。

Protocol: HTTP
Dataformat : JSON/XML
Authentication : API key/Oauth

库和SDK的API实现：
创建应该在整个生命中冻结的原型通过添加额外函数来扩展API，而不是更改现有函数原型允许用户提供尽可能多的输入作为函数的参数。因此，应用程序可以按照用户的要求完成其工作。

请牢记用户，API应该允许用户轻松使用它。

参见：
API简介：https://zapier.com/learn/apis

编写API的建议

4 个答案: