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

Question

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

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

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

score 12 · Accepted Answer

阅读RESTful Web 服务这本书，它为您提供了如何在实践中使用 REST 的一个很好的概述，并以足够快的速度开始使用，并且有一定的信心。这比仅查看现有 API 更有用，因为它还讨论了设计选择和权衡。

score 8 · Accepted Answer

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 漏洞。

score 7 · Accepted Answer

我会看看经过验证的 API：

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

score 6 · Accepted Answer

使用REST。

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

亚马逊网络服务、谷歌和许多其他公司提供 REST API 来与他们的产品进行交互。

score 3 · Accepted Answer

使用 REST。

阅读 API 标准，或复制其中一种流行的想法。

验证用户时要小心。

开始非常非常简单。

建立一个使用你的 API（即使它没有用）来检查事情是否有效的网站。也许您可以构建网站的移动版本或强制您深入使用 API 的东西。

5 回答 5