我应该如何构建一个好的（网络）API

Question

我将为一个网络应用程序构建一个 API，并且我对人们可以建议的良好实践感兴趣。

我已经计划对其进行版本控制（版本 1 只能控制系统的某些方面，版本 2 可以控制更多，但这可能需要更改执行身份验证的方式，这与版本 1 不兼容），并且身份验证将不同于人们用来登录的标准用户名/密码（如果有人确实使用恶意工具，它不会让他们完全模仿，无论 API 允许什么）。

有没有人有进一步的想法，或者您使用过的具有特别好的 API 的网站示例？

Answer 1

阅读 RESTful Web 服务 本书，它让您很好地概述了如何在实践中使用 REST，并快速上手，现在就充满信心地开始使用。这比仅仅查看现有 API 更有用，因为它还讨论了设计选择和权衡。

Answer 2

1) 将版本号直接烘焙到 URL 中，而不是将其作为参数传递，因为这样您就可以完全自由地在每次版本更新时更改 API 命名空间的组织。

2) 使您的 URL 重写规则（如果有）尽可能简单/精简（但不能更简单），同时使您的 URL 尽可能美观（但仅此而已）。

3) 始终为每个响应寻找可以找到的最佳 HTTP 状态代码（例如，不要忘记 202 和 207）。

4) 实施法西斯参数验证逻辑和信息错误消息。

5) 在适当的情况下使用 HTTP 请求标头而不是参数（例如，Accept，以允许客户端指定所需的响应数据格式）。

6) 以这样的方式组织你的“名词”，使不同客户端受众使用的 URL 在 URL 树的“根”附近分开（这使得在需要时更容易为这些不同的受众实施不同的身份验证机制，甚至映射URL 树的不同部分到不同的服务器）。

7) 如果您在与 API 相同的域中提供常规网页并使用相同的身份验证凭据，则需要在 API 请求中包含 X-Requested-With 标头，以避免 XSRF 漏洞。

Answer 3

我会看一下经过验证的 API：

1. YouTube API
2. 推特API

关于这些 API 是否“好”存在很多争论，但我认为它们的成功已经得到证明，而且它们都很易于使用。

Answer 4

使用 休息.

RESTful Web 服务架构易于实现，并利用 HTTP 的优势和语义来实现其预期目的。它是面向资源的，就像网络本身一样。

亚马逊网络服务, 、Google 和许多其他公司提供 REST API 来与其产品交互。

Answer 5

使用休息。

阅读 API 标准，或者复制流行标准之一的想法。

验证用户身份时要小心。

开始非常非常简单。

构建一个使用您的 API（即使它没有用）的网站来检查一切是否正常。也许您可以构建网站的移动版本或迫使您深入使用 API 的东西。