在为基于社区的网站构建 API 之前，开发人员应该了解什么？

Question

在开始繁重的编码之前，为基于社区的网站设计和实现 API 的开发人员应该了解哪些内容？有很多 API，例如 Twitter API、Facebook API、Flickr API 等，这些都是很好的例子。但是你会怎么build your own API？

您会使用哪些技术？我认为使用类似REST 的接口是一个好主意，以便可以从不同的平台/客户端/浏览器/命令行工具（如curl）访问API。我对吗？我知道应该满足 Web 开发的所有原则，例如缓存、可用性、可扩展性、安全性、防止潜在的 DOS 攻击、验证等。当涉及到 API 时，一些最重要的事情是向后兼容性和文档。我错过了什么吗？

另一方面，从用户的角度考虑（我是指将使用您的 API 的开发人员），您会在 API 中寻找什么？好的文档？大量代码示例？

这个问题的灵感来自Joel Coehoorn 的问题"What should a developer know before building a public web site?"。

这个问题是一个社区 wiki，所以我希望你能帮助我将在为基于社区的网站构建 API 时应该解决的所有问题放在一个地方。

Answer 1

如果你真的想定义一个 REST api，那么请执行以下操作：

1. 忘记 HTTP 和媒体类型以外的所有技术问题。

2. 确定客户端将与 API 交互的主要用例

3. 编写针对假设的 HTTP 服务器执行这些“用例”的客户端代码。 客户端应该开始使用的唯一信息是从 GET 请求到根 API url 的响应。客户端应从 HTTP 内容类型标头中识别响应的媒体类型，并解析响应。该响应应包含指向允许客户端执行所有 API 所需操作的其他资源的链接。

   创建 REST api 时，更容易将其视为机器的“用户界面”，而不是公开对象模型或流程模型。想象一下机器通过检索响应、跟踪链接、处理响应并跟踪下一个链接以编程方式导航 api。 客户端不应根据其对服务器如何组织资源的了解来构造 URL。

4. 这些链接的格式和标识方式至关重要。 您在定义 REST API 时将做出的最重要决定是您对媒体类型的选择。您要么需要找到表示该链接信息的标准方法（想想Atom、microformats、atom link-relations、Html5 link relations），或者如果您有特殊需求并且不需要真正广泛接触许多客户，那么你可以创建自己的media-types。

5. 记录这些媒体类型的结构以及它们可能包含的链接/链接关系。有关媒体类型的特定信息对客户来说至关重要。如果客户端想要做的不仅仅是解析响应，让服务器返回 Content-Type:application/xml 对客户端毫无用处。客户端无法知道 application/xml 类型的响应中包含什么。有些人确实相信您可以使用 XML 模式来定义它，但它有几个缺点，它违反了 REST“自我描述消息”约束。

6. 请记住，URL 的外观与客户端的操作方式完全无关。唯一的例外是媒体类型可以指定模板化 URI 的使用，并且可以定义这些模板的参数。 在选择服务器端框架时，URL 的结构将变得很重要。服务器控制 URL 结构，客户端不应该关心。但是，不要让服务器端框架决定客户端如何与 API 交互，并且在选择需要更改 API 的框架时要非常谨慎。 HTTP 应该是关于客户端/服务器交互的唯一约束。