RESTful API 是一种以资源为中心、通过 HTTP 协议访问的 API 设计风格，它已被广泛应用于 Web 开发中。为了提高 API 的可用性和可维护性，以下是我们总结的十条 RESTful API 设计最佳实践。
1. URI 应该表示资源
URI 应该直观地反映出所请求的资源。这就要求 URI 的设计不应过于简单，应该考虑资源的分类和关系。比如，当我们要获取用户发表的所有文章时，可以请求类似 /users/{userId}/posts 的 URI，其中 {userId} 表示用户 ID。
2. 使用 HTTP 动词
HTTP 协议本身就规定了几种动词（例如 GET、POST、PUT、DELETE），可以用来对资源进行不同的操作。我们应该根据具体的需求选择对应的 HTTP 动词。
比如，当我们要创建一篇新文章时，使用 POST 方法对应的 URI 应该是 /users/{userId}/posts/，而当我们要更新已有的文章时，使用 PUT 方法对应的 URI 应该是 /users/{userId}/posts/{postId}。
3. URI 不应该包含动词
和上一条相对应，URI 直接表示资源，因此不应该包含动词。应该使用 HTTP 动词来表示具体的操作。
例如，不应该使用类似 /users/{userId}/createPost 或 /users/{userId}/updatePost 的 URI。
4. 尽可能使用动词短语
虽然 URI 不应该包含动词，但是为了让 URI 更清晰易懂，我们可以尽量使用动词短语来描述语义。例如，使用类似 /users/{userId}/likes 的 URI 代表用户喜欢的文章列表，使用类似 /users/{userId}/posts/{postId}/like 的 URI 代表给某篇文章点赞。
5. 使用 HTTP 状态码
HTTP 协议规定了多个状态码作为响应返回给客户端，我们可以使用这些状态码来表示 API 的执行结果。比如，使用 200 状态码表示操作成功，使用 404 状态码表示请求的资源不存在，使用 401 状态码表示用户未经授权等。
6. 使用 JSON 格式
JSON 是一种轻量级的数据格式，已经成为大多数 RESTful API 中数据传输的标准。通常我们使用 POST 或 PUT 方法时将数据以 JSON 格式的字符串形式作为请求体发送到服务器。
以下是一个使用 Node.js Express 框架实现的示例：
-- -------------------- ---- ------- -- ------- -------------------------------- ----- ---- -- - ----- - ------ - - ----------- ----- -------- - --------- -- - -------- ------- ------------------- ---
7. 使用版本号控制
当我们对 API 进行一些不兼容的更改时（例如修改 URI 格式或者请求体的结构），我们应该考虑使用版本号来控制。通过使用版本号，我们可以让客户端在需要升级时进行相应的更改，同时保证旧版本的 API 可稳定运行。
8. 使用身份验证和授权
为了保护 API 的安全性，我们需要对 API 的访问进行身份验证和授权。我们可以使用 JWT、OAuth 等身份验证机制来验证身份，同时在 API 的设计中考虑不同用户的权限等级。
9. 使用查询参数过滤结果
查询参数是一种常见的筛选 API 结果的方法。我们可以在 URI 中加入查询参数，让 API 返回符合条件的结果。例如，我们可以使用类似 /users/{userId}/posts?status=published 的 URI，来获取某用户已发布的文章列表。
10. 使用超媒体链接
超媒体链接是一种让 API 返回的资源包含指向相关资源的链接的方法。通过使用超媒体链接，我们可以实现 API 的自描述，让客户端更容易地理解 API 的使用方法和资源之间的关系。
以下是一个简单的使用超媒体链接的示例：
-- -------------------- ---- -------
-
--------- --
-------- ------ -------
---------- -----------
--------- -
------- - ------- ------------------ --
--------- - ------- ---------- --
----------- - ------- --------------------------- -
-
-在上面的示例中，使用 _links 字段表示这个资源对应的超媒体链接。其中 self 表示这篇文章自身的链接，author 表示作者的链接，comments 表示这篇文章的评论链接。
总之，RESTful API 的设计是一项需要认真思考和细心实现的工作。以上十条最佳实践可以帮助我们更好地设计和维护 RESTful API。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/64f16bf2f6b2d6eab3b3f39c