RESTful 是一种轻量级的架构风格，可以使得前后端的分离更加清晰，实现简单的 API 开发。但如何发布和管理 RESTful API 是一个很复杂的问题。本文将解析RESTful API 的最佳实践，并分享一些指导性的经验。
1. 命名规范
命名规范是让维护者易于理解 API 的方式。严格规定 HTTP 动词，URL 及其参数，JSON 传输格式以及错误报告，使 API 保持一致性和透明度。某些使用国际标准的资源 API（例如用于 Vimeo 视频的 API）同时符合 RESTful API 的命名规范。
2. 版本控制
API 版本控制通常是必需的，因为不同的客户端和应用程序在调用同一 API 时需要使用不同的参数和规则。由于任何修改都会影响客户端，所以最好通过 API 访问方式指定 API 版本。
例如，可以在各自对应的 URL 中加入 API 版本号：www.example.com/api/v1 和 www.example.com/api/v2。或者更好的方法是将版本号作为 HTTP 头信息（例如“API-Version：2”），这样客户端程序就不需要在 URL 内的请求参数中硬编码版本号。
3. 规范 HTTP 错误状态码
HTTP 错误状态码是用来告诉 API 用户请求失败的原因。正确的错误状态码有助于 API 用户了解何时重新尝试请求或如何修复错误。使用正确的状态码可避免混淆并为 API 用户提供必要的信息。以下是几个常见的状态码及其相应的含义。
200 OK- 请求已成功201 Created- 请求成功且新资源已创建204 No Content- 请求成功，但没有数据返回400 Bad Request- 服务器无法理解请求401 Unauthorized- 没有身份验证信息或身份验证信息无效403 Forbidden- 客户端没有权限访问此资源404 Not Found- 请求的资源不存在500 Internal Server Error- 服务器发生故障
4. 定义 API 返回格式
API 响应格式是指服务器返回给 API 调用者的格式。通常采用 JSON（JavaScript Object Notation）作为响应格式，因为它既易于阅读，也易于在前端 JavaScript 中处理。额外的响应格式（例如 XML）可能会易于解决预存（适用于固定数据模板）。
在 API 响应格式中，还可以包括超媒体链接，这些链接可以在每个响应中隐藏并告诉客户端下一步应该执行什么操作。
5. 安全
安全被认为是 API 开发中最重要的方面之一。确保 API 是安全的，可以通过一些措施来实施，如：
- 使用公共密钥和私有密钥访问 API。
- 限制在特定 IP 范围内的 API 访问。
- 实施加密措施。
6. 测试 API
测试代码必须与 API 发布包含的端点集成。在发布之前或与新版本一起发布测试 API 可以帮助团队验证交流中的细节，例如 API 的 JSON 响应格式，API 错误的正确状态代码和安全措施。确保测试用例的状态在所有系统上都是一致的，例如转换一些请求到奇怪的数据格式，如果显示不一致，则可以得出特定格式的应用程序更容易失败等。
下面是一些示例应用程序：
-- -------------------- ---- ------- -- --- --- ------ ----------------------- ------------- ---- - --- ----- - ------- --------- ------ ---------- ---------------- --- - -- --- - ---- -- ----- ----------------------------- ------------- ---- - --- ---- - ------ ----------------- --------------- --- - -- ------ - ---- -- ----- -------------------------------- ------------- ---- - -- ------ ----- ---- ------- ----------------- ------------ --- - -- ------ - --- ----- ------------------------ ------------- ---- - -- ------ ----- ---- ------- ----------------------------- ------------ ---
总结
在本文中，我们学习了一些有关发布 RESTful API 的最佳实践，包括规范的 HTTP 错误状态码，定义 API 返回格式，安全等。当实施这些策略时，还应指定易于用来理解和维护 API 的命名规范，并对 API 进行测试，以确保其正确运行。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/6452578b968c7c53b06f7ead