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

Question

在开始繁重的编码之前，为基于社区的网站设计和实现 API 的开发人员应该知道什么？有很多 API，例如 Twitter API , Facebook API , Flickr API等都是很好的例子。但是你会怎么做build your own API ?

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

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

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

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

Answer 1

如果您真的想定义一个 REST api，请执行以下操作:

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

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

编写针对假设的 HTTP 服务器执行这些“用例”的客户端代码。 客户端应该开始的唯一信息是从 GET 请求到根 API url 的响应。 .客户端应从 HTTP 内容类型 header 中识别响应的媒体类型，并解析响应。该响应应包含指向允许客户端执行所有 API 所需操作的其他资源的链接。
在创建 REST api 时，更容易将其视为机器的“用户界面”，而不是公开对象模型或流程模型。想象一下机器通过检索响应、跟踪链接、处理响应并跟踪下一个链接以编程方式导航 api。 客户端不应该根据其对服务器如何组织资源的了解来构造 URL .

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

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

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