题
我将为一个网络应用程序构建一个 API,并且我对人们可以建议的良好实践感兴趣。
我已经计划对其进行版本控制(版本 1 只能控制系统的某些方面,版本 2 可以控制更多,但这可能需要更改执行身份验证的方式,这与版本 1 不兼容),并且身份验证将不同于人们用来登录的标准用户名/密码(如果有人确实使用恶意工具,它不会让他们完全模仿,无论 API 允许什么)。
有没有人有进一步的想法,或者您使用过的具有特别好的 API 的网站示例?
解决方案
阅读 RESTful Web 服务 本书,它让您很好地概述了如何在实践中使用 REST,并快速上手,现在就充满信心地开始使用。这比仅仅查看现有 API 更有用,因为它还讨论了设计选择和权衡。
其他提示
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 漏洞。
使用休息。
阅读 API 标准,或者复制流行标准之一的想法。
验证用户身份时要小心。
开始非常非常简单。
构建一个使用您的 API(即使它没有用)的网站来检查一切是否正常。也许您可以构建网站的移动版本或迫使您深入使用 API 的东西。