当前位置：首页 > 科技 > 软件

构建强大REST API的十个最佳实践

来源：责编：时间：2023-12-06 09:19:57 339观看

导读在项目开发中，我们经常会使用REST风格进行API的定义，这篇文章为大家提供10条在使用REST API时的最佳实践。希望能够为你带来灵感和帮助。1、使用具体且有意义的资源名称选择能准确表示所代表实体的资源名称，而不要使用泛

在项目开发中，我们经常会使用REST风格进行API的定义，这篇文章为大家提供10条在使用REST API时的最佳实践。希望能够为你带来灵感和帮助。

1、使用具体且有意义的资源名称

选择能准确表示所代表实体的资源名称，而不要使用泛化或模糊的名称。

图片

这一条最佳实践非常明确，也就是说我们在使用REST API时，代表资源分类的部分，比如上图中的“users”和“customers”，使用users更泛化，不够具体，可能是To C的用户，也可能是To B或To G的用户。此时，最近确保定义的资源更具体，能够代表一定的清晰含义。

2、正确使用HTTP方法

根据不同的操作使用合适的HTTP方法（GET、POST、PUT、DELETE、PATCH等）。

图片

这一条涉及到HTTP方法的基本定义。举一个简单的例子来说明就是：一般提交表单操作，用POST请求，查询信息用GET请求。不要将两者颠掉或混用。当然，还有其他的HTTP方法，也是如此。

3、对API进行版本控制

使用版本控制确保向后兼容性，并允许在不破坏现有客户端的情况下进行未来的增强。

图片

为了保持版本的兼容性，依旧流量和功能的控制等，通常需要对API进行版本控制，这个是仅限于REST API，而是比较通用的一条最佳实践，特别是真的终端是APP的情况。

4、正确使用HTTP状态码

返回适当的HTTP状态码以指示API请求的成功或失败。

图片

这一条也是非常基础的HTTP知识，不同的错误码代表着不同的含义，准确的返回错误码，可以让终端更加精准的识别错误。

5、选择JSON字段命名约定

JSON标准没有强制规定字段命名约定，但最佳实践是选择一个并坚持使用。

图片

选择适合团队和编程语言的JSON命名规则，具体采用哪种不重要，重要的是整个团队要确保统一。在个人的团队中，更习惯使用驼峰（camelCase）的形式。

6、使用一致的错误信息

在大多数情况下，仅使用HTTP状态码无法解释出现的错误。为了帮助API使用者，包含一个结构化的JSON错误消息。这里的JSON错误信息更偏向业务层面。而HTTP状态码更偏向于HTTP交互层面。

响应应包括以下信息：

错误代码：机器可读的错误代码，用于识别特定的错误条件。
错误消息：人类可读的消息，提供对错误的详细解释。
错误上下文：与错误相关的附加信息，例如请求ID、导致错误的请求参数或导致错误的请求中的字段。
错误链接：提供有关错误以及如何解决错误的附加信息或文档的URL。
时间戳：错误发生的时间。

7、使用查询参数进行过滤、排序和搜索

查询参数允许你在HTTP请求的URL中提供额外的信息，以控制服务器返回的响应。

图片

8、实施身份验证和授权

通过实施适当的身份验证和授权机制来保护API。

建议：

使用API密钥、令牌或OAuth 2.0进行身份验证
应用基于角色的访问控制（RBAC）进行授权

9、不要维护状态

REST API不应在服务器上维护状态，这是客户端的责任。这很重要，因为它可以使API具备可缓存性、可扩展性，并使其与客户端解耦。

例如，电子商务API可能使用cookie来维护购物车的状态。然而，这种方法违反了RESTful API的关键原则：它们需要是无状态的。

10、文档化你的API

为你的API提供全面的文档，包括端点细节、请求/响应示例和使用指南。

建议：

Swagger/OpenAPI文档
基于Markdown的文档（例如，使用Swagger UI或Redoc等工具）

本文链接：http://www.28at.com/showinfo-26-38524-0.html构建强大REST API的十个最佳实践

声明：本网页内容旨在传播知识，若有侵权等问题请及时与本网联系，我们将在第一时间删除处理。邮件：2376512515@qq.com

上一篇：前端请求到后端API的中间件流程解析

下一篇：作为一名 Go 程序员，我为啥更喜欢用 Zig？

标签：

热门焦点

一篇聊聊Go错误封装机制

%w 是用于错误包装（Error Wrapping）的格式化动词。它是用于 fmt.Errorf 和 fmt.Sprintf 函数中的一个特殊格式化动词，用于将一个错误（或其他可打印的值）包装在一个新的错误中。使
企业采用CRM系统的11个好处

客户关系管理（CRM）软件可以为企业提供很多的好处，从客户保留到提高生产力。　　CRM软件用于企业收集客户互动，以改善客户体验和满意度。　　CRM软件市场规模如今超过580
微信语音大揭秘：为什么禁止转发？

大家好，我是你们的小米。今天，我要和大家聊一个有趣的话题：为什么微信语音不可以转发？这是一个我们经常在日常使用中遇到的问题，也是一个让很多人好奇的问题。让我们一起来揭开这
腾讯盖楼，字节拆墙

来源 | 光子星球撰文 | 吴坤谚编辑 | 吴先之“想重温暴刷深渊、30+技能搭配暴搓到爽的游戏体验吗？一起上晶核，即刻暴打！”曾凭借直播腾讯旗下代理格斗游戏《DNF》一
重估百度丨大模型，能撑起百度的“今天”吗?

自象限原创作者｜程心罗辑2023年之前，对于自己的“今天”，百度也很迷茫。“新业务到 2022 年底还是 0，希望 2023 年出来一个 1。”这是2022年底，李彦宏
造车两年股价跌六成，小米的估值逻辑变了吗？

如果从小米官宣造车后的首个交易日起持有小米集团的股票，那么截至2023年上半年最后一个交易日，投资者将浮亏59.16%，同区间的恒生科技指数跌幅为52.78%
三星显示已开始为AR设备研发硅基LED微显示屏

7月18日消息，据外媒报道，随着苹果首款头显产品Vision Pro在6月份正式推出，AR/VR/MR等头显产品也就将成为各大公司下一个重要的竞争领域，对显示屏这一关
支持aptX Lossless无损传输 iQOO TWS 1赛道版发布限时优惠价369元

2023年7月4日，“无损音质，声动人心”iQOO TWS 1正式发布，支持aptX Lossless无损传输，限时优惠价369元。iQOO TWS 1耳机率先支持端到端aptX Lossless无
由于成本持续增加，笔记本产品价格预计将明显上涨

根据知情人士透露，由于材料、物流等成本持续增加，笔记本产品价格预计将在2021年下半年有明显上涨。进入6月下旬以来，全球半导体芯片缺货情况加剧，显卡、处理器

构建强大REST API的十个最佳实践

1、使用具体且有意义的资源名称

2、正确使用HTTP方法

3、对API进行版本控制

4、正确使用HTTP状态码

5、选择JSON字段命名约定

6、使用一致的错误信息

7、使用查询参数进行过滤、排序和搜索

8、实施身份验证和授权

9、不要维护状态

10、文档化你的API

一篇聊聊Go错误封装机制

企业采用CRM系统的11个好处

微信语音大揭秘：为什么禁止转发？

腾讯盖楼，字节拆墙

重估百度丨大模型，能撑起百度的“今天”吗?

造车两年股价跌六成，小米的估值逻辑变了吗？

三星显示已开始为AR设备研发硅基LED微显示屏

支持aptX Lossless无损传输 iQOO TWS 1赛道版发布限时优惠价369元

由于成本持续增加，笔记本产品价格预计将明显上涨

最新推荐

猜你喜欢

热门推荐

相关资讯