RESTful API 是现代 Web 应用的关键组成部分之一。这类 API 可以从任何网络连接设备中访问，提供了许多与平台无关的接口，允许开发者构建高度可扩展的应用程序。但是，开发干净、易用的 RESTful API 并不是易事。本文将会从实践中学习，探讨如何设计干净、易用的 RESTful API。
RESTful API 设计的基础原则
RESTful API 设计并没有如此固定的标准，但是仍然有一些基本的设计原则可以使我们的 API 更加易用和干净。以下是一些应该考虑的基本原则：
1. 定义明确的资源
RESTful API 是基于资源的。你定义的每个 API 都应该涉及到一个或多个资源。例如，一个社交网络应用可以有 "user" 和 "post" 两种资源。对于每个资源，你应该定义:
- 联结这些资源的唯一标识符 (URL)
- 它支持的 HTTP 方法和操作
- 它能返回的不同状态
- 它所需要的认证策略
2. 将操作映射到 HTTP 方法
HTTP 定义了一组基本的动词，这些动词对应于一组基本的 CRUD 操作：创建 ('POST')，读取 ('GET')，更新 ('PUT')，删除 ('DELETE')。将这些动词映射到你的资源上，是强制实现 RESTful API 的另一种方式。
3. 使用 URL 构建资源层级结构
RESTful API 使用 URL 来定义资源及其关系。这些关系应该在 URL 的层级结构中得到体现。例如，在上述社交网络应用中，如下 URL 结构应该合理：
/users # returns a list of all users /users/123 # returns information about the user with id=123 /users/123/posts # returns all posts made by user 123
虽然这个 URL 结构是很流行的一种实现方式，但你并不一定需要像这样实现。你应该根据你的应用程序需求，进行灵活的 URL 设计。
4. 使用适当的 HTTP 状态码
HTTP 状态码应该告诉客户端关于请求的结果的重要信息。例如，站点不存在应该返回 404 状态码，用户没有权限应该返回 403 状态码，资源已被删除应该返回 410 状态码。使用适当的状态码可以让客户端更好地理解服务端的返回结果。
5. 不要滥用 POST 请求
POST 请求用于创建资源，而 PUT 请求用于更新资源。如果你试图用 POST 请求来修改资源，那么你就没有遵循这个最好实践原则。滥用 POST 请求通常会导致 API 设计上的混乱。
示例代码
现在，让我们来写一个类似社交网络应用的 API，其中涉及两种资源：用户 ("users")和他们发布的帖子 ("posts")。以下代码示例演示了如何使用以上原则设计简单的 RESTful API。
-- -------------------- ---- -------
- --- ------ ------
--- ------------
------ -
------ -- ------- ---------
------ -- ------- -------
------ -- ------- ----------
-
- --- ---------------- ------
--- ------------------
----- - -----------
--- ---- -- ------
-- ---------- -- --------
------ ----
------ ----
- --- ---------------------- -------------
--- ------------------------
------ -
------ -- ---------- -------- ------- --- ----- --------
------ -- ---------- -------- ------- ---- ----- ----- --- -- --- ---- --------
-
- ---- ------ ------
--- ------------------
----- - -----------
------- - --------------- --- ---- -- ------- - -
------------------- -------- ------- ------
------ ------ -------- ------- -----
- --- ---------------- ------
--- -------------------- ------
----- - -----------
--- ---- -- ------
-- ---------- -- --------
------------ - ----
------ ----
------ ----
- ------ ---------------- ------
--- ---------------------
----- - -----------
--- -- ---- -- -----------------
-- ---------- -- --------
------------
------ ----
------ ----结论
在本文中，我们学习了一些基本的 RESTful API 设计原则。虽然这些原则并不是像套路一样固定的，但它们可以成为你设计良好的 API 架构的参考。请记住，RESTful API 的设计应该始终以简单和可读性为基础，仅根据项目需求进行灵活的调整。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/6717768dad1e889fe221b52f