RESTful API（RESTful API）是一种用于网络应用程序间交互的设计风格。REST是一组架构原则和约束，而不是具体的协议或标准。当一个网络服务遵循“RESTful”风格时，它提供高效、可靠且可扩展的网络服务。

在 RESTful 服务里，每个请求都应包含处理所需的所有必要信息。服务器不应保留任何关于客户端请求的状态。

基于REST的架构可以包含多个层次，每个层次都有其特定的功能。这种结构有助于开发更复杂且功能强大的应用程序。

URI 规划

在 RESTful API 设计中，URL 表示资源（对象），而 HTTP 方法（如 GET、POST、PUT、DELETE 等）表示对资源的操作。这种设计风格更侧重于资源的状态和表现，而不是具体的动作。

动词加宾语

RESTful API 中的动词通常是指常见的五个 HTTP 方法，对应 CRUD 操作中的功能：

• GET : 读
• POST : 创建
• PUT : 更新
• PATCH : 修改（通常用于局部修改）
• DELETE : 删除

按照 HTTP 协议的要求，动词应该始终使用大写。

目标得是具体的东西

在设计API时，URL（统一资源定位符）通常表示一个资源，这个资源是HTTP动词作用的对象。根据RESTful设计的指导原则，URL应为名词而非动词，因为它们表示的是“资源”集合或单个实例，而不是表示动作。

以下是一些错误示例：

• /获取所有车辆
• /创建新车
• /删除所有红色车

这些URL包含了诸如get、create、delete之类的动词，描述的是操作而不是资源本身。这种设计并不符合RESTful语义规范。

正确的做法：

URL应该主要描述资源，而不是描述操作。以下是一些符合规范的URL设计示例：

• /users: 表示所有用户
• /users/123: 表示ID为123的单个用户信息

在上面的例子中，/users 和 /users/123 都是名词，分别表示用户列表和特定用户。这样的 URL 设计让 API 更容易理解，并且符合 RESTful 风格的原则。

通过采用此命名约定，这样可以确保API路径清晰、一致且易于理解与维护。

多个URL

通常建议在URL中使用复数形式，因为这有助于保持一致性和清晰性，同时它们通常表示资源的集合。

当你的URL指向一个资源集合时，使用复数形式。例如，使用 /users 而不是 /user 来表示所有用户。

即使指向单一资源，也建议使用复数形式的表述。例如， /users/123 代表的是 ID 为 123 的用户。这种方法有助于保持 URL 的一致性。

当资源之间存在层级关系时，URL 应该体现出这种层级关系。例如，/users/123/posts 可以代表用户 123 的所有帖子。

避免URL的深层嵌套

一个常见的场景是资源需要分多个层级进行分类，导致URL结构变得非常复杂，例如，检索某个特定作者的某一类文章：

    GET /作者ID/12/分类ID/2

全屏 退出全屏

这样的URL不仅难以扩展，其含义也往往不明确，通常需要额外的努力去理解。更好的办法是使用多级查询参数。

GET /作者们/12?分类=2

进入全屏模式：点击这里，退出全屏模式：点击这里

另一个例子是查找已发布文章时设计 URL，可以这样做：

GET /articles/published

切换到全屏 退出全屏

不过，使用查询参数显然更好。

    GET /articles?published=true 获取已发布的文章列表

全屏模式/退出全屏

常见状态码

状态代码必须准确

对于每个客户端的请求，服务器必须用一个HTTP状态码和相应的数据作出回应。

HTTP状态码是由三位数字组成的，这些数字被分为五大类。

• 1xx ：信息提示
• 2xx ：成功状态
• 3xx ：重定向提示
• 4xx ：客户端问题
• 5xx ：服务器问题

这五个类别包含了超过100个状态码，涵盖了大多数可能的情况。每个状态码都有一个标准（或通常接受）的意义，让客户端只需查看状态码就能知道发生了什么。因此，服务器最好返回尽可能精确的状态码。

APIs 不需要 1xx 状态码的。下面是其余四类的解释。

2xx 状态码简介

不同的 HTTP 请求方法应返回相应的状态码以指示请求结果。虽然 200 OK 通常表示请求成功，但应根据具体的请求方法选择更合适的状态码。

• GET: 200 OK – 请求成功，资源被返回。
• POST: 201 Created – 新的资源成功创建，响应通常包含资源的URI。
• PUT: 200 OK 或 204 No Content – 用于更新完整资源。如果返回内容，使用 200；如果没有，使用 204。
• PATCH: 200 OK 或 204 No Content – 用于部分更新操作，类似于PUT。204 表示没有内容返回。
• DELETE: 204 No Content – 表示资源已被成功删除，响应通常不包含内容。
• 202 Accepted – 请求已被接受但尚未处理，适用于异步处理。
• 206 Partial Content – 表示部分响应内容，通常用于客户端使用 Range 头请求大文件的一部分时。

3xx 重定向状态码

APIs 一般不使用 301（永久重定向） 或 302（临时重定向），因为这些状态码主要用于浏览器导航。应用层级可以处理这些情况。

然而，APIs 可能使用 303 See Other，这会指向另一个 URL。就像 302 和 307 一样，它表示“临时重定向”，但 303 主要用于 POST、PUT 和 DELETE 请求。与 302 不同，浏览器不会自动处理 303 重定向，而是让用户自己决定下一步。

比如说，一个例子的回应：

    HTTP/1.1 303 重定向
    Location: /api/orders/12345

全屏模式 退出全屏

4xx 错误代码

4xx HTTP状态码表示客户端错误。常见的包括：

• 400 错误请求 – 服务器无法理解客户端的请求，因此未进行处理。
• 401 未授权 – 用户未提供认证凭据或认证失败。
• 403 禁止访问 – 用户虽然成功认证，但无权访问该资源。
• 404 资源不存在 – 请求的资源不存在或不可用。
• 405 方法无法使用 – 用户虽然成功认证，但使用了不允许的 HTTP 方法。
• 410 已消失 – 请求的资源已被永久移除。
• 415 未支持的媒体类型 – 请求的格式不被支持。例如，如果 API 只返回 JSON，但客户端请求 XML，应返回此状态。
• 422 无法处理的实体（内容） – 客户端提供的附件无法被处理，导致请求失败。
• 429 请求过多，已超出允许的请求数量 – 客户端已超出允许的请求数量。

5xx 状态码

5xx 状态码表示服务器出现了错误。API 通常不会向用户透露服务器内部的详细信息，因此通常只用到两个状态码。

• 500 内部服务器错误 – 有效的客户端请求，处理请求时遇到意外问题。
• 503 服务不可用 – 服务器暂时无法处理请求的能力，通常在维护期间出现。

服务器响应消息

请勿返回纯文本内容

API 响应不应是纯文本，而应使用结构化的 JSON，以确保格式标准化。服务器应将 Content-Type 标头设置为 application/json。

客户端还应在请求中设置Accept头部为application/json，以指定其接受JSON响应。

发送以下 HTTP 请求来获取订单信息：

GET /orders/2 HTTP/1.1
Accept: application/json

这将请求服务器返回订单 2 的 JSON 格式数据。

点击进入全屏，点击退出全屏

遇到错误时，不要返回 200 状态码

错误的做法是即使发生错误也总是返回 200 OK，并将错误详情包含在响应体中。这迫使客户端解析响应体来判断请求是否失败，从而违背了状态码设计的初衷。

一个糟糕的例子，比如说：

HTTP/1.1 200 OK
Content-Type: application/json
{
  "状态": "失败",
  "数据": {
    "错误": "期望列表中至少包含两个元素。"
  }
}

点击进入全屏，点击退出全屏

在这种情况下，请求失败了，但服务器仍然返回了 200 OK。客户端需要检查响应体中的 "status": "failure" 字段来检测错误。这种方法不遵循RESTful规范，使得错误处理更复杂且容易出错。

一个正确的例子：

状态码应反映请求的结果。错误应通过适当的状态码反馈，而响应体则提供更多详细信息。

当请求无效时，服务器应返回 400 Bad Request，并将错误详情以 JSON 格式返回。

    HTTP/1.1 400 错误：坏请求
    Content-Type: application/json
    {
      "error": "无效的请求体。",
      "detail": {
        "surname": "此字段是必填项。"
      }
    }

全屏模式 退出全屏

在这里，400 明确表示请求无效，响应体则提供具体的错误细节，以便客户端更好地理解问题。

分享链接

在 RESTful API 中，响应中包含链接是一种常见的做法。这遵循了“超媒体作为应用状态引擎 (HATEOAS)”的原则，使 API 更易于发现和自我描述。

这里有，两种常见的方式添加链接：

使用 HAL（超文本应用语言）时

HAL 是一种流行的超媒体格式，用来展示资源之间的关系，它通过 JSON 响应中的 _links 字段实现。

{
  "id": 1,
  "name": "例子",
  "_links": {
    "self": {
      "href": "http://api.example.com/resource/1"
    },
    "related": {
      "href": "http://api.example.com/resource/2"
    }
  }
}

全屏模式 退出全屏

直接在 JSON 中插入链接

    {
      "id": 1,
      "name": "例子",
      "links": {
        "links": "关联",
        "self": "http://api.example.com/resource/1",
        "related": "http://api.example.com/resource/2"
      }
    }

全屏模式（F）退出全屏模式（Esc）

退货政策（针对内容）

在设计 RESTful API 时，POST 请求用于创建新资源。是否在响应中包含新创建的资源，这取决于实现的具体需求。通常有两种常见的方法：

1. 返回创建的资源项

这种做法包括一个 201 Created 状态码，并在响应中提供新资源的所有详细信息。此外，还包括一个 Location 标头，指向资源的 URI。

HTTP/1.1 201 创建响应
位置: /resources/123
Content-Type: application/json
{
  "id": 123,
  "名称": "新资源"
}

进入全屏 退出全屏

2. 不要返回内容数据

另外，服务器也可以选择仅返回一个 201 Created 或 204 No Content 响应，并同时包含一个 Location 标头，不发送资源的具体信息。这样可以减少数据传输，并让客户端自行决定是否稍后再获取资源。

HTTP/1.1 201 创建响应
Location: /resources/123

进入全屏 退出全屏

结论部分:

RESTful API遵循HTTP协议，强调资源的表现和无状态性。通过使用标准的HTTP方法（GET、POST、PUT、DELETE）和明确的状态码，RESTful架构提供了一种简单、高效和易于维护的方式来构建网络应用程序。这种架构增强了Web服务的可扩展性、灵活性和可维护性。

此处无正文
此处省略了内容

我们是 Leapcell，您托管后端项目的首选之地。

（https://leapcell.io/?lc_t=d_restful）

Leapcell（https://leapcell.io/?lc_t=d_restful）是新一代的无服务器平台，用于网站托管服务、异步任务处理和 Redis。

支持多语言

• 使用以下技术之一：Node.js、Python、Go 和 Rust 开发。

免费部署任意数量的项目.

只按实际使用付费，不用不收钱。

超值性价比

• 按需计费，无闲置时长费用。
• 例如：比如，$25可以支持6.94M次请求，平均响应时间仅为60毫秒。

流畅的开发体验

• 直观的用户界面，让设置变得轻松。
• 完全自动化的CI/CD pipeline和GitOps集成。
• 实时指标和日志，提供可操作的见解。

轻松扩展性和高性能

• 自动扩展，轻松应对高并发。
• 零运营成本，只需专注于开发。

点击这里了解更多！或更多详情，请参阅文档!

关注我们的X账号[@LeapcellHQ]

---

在我们的博客上了解更多