一、前言

目前，RESTful API 已经成为Web应用程序的标准API设计风格，受到广泛的应用和支持，其中Swagger、OpenAPI等工具的出现进一步简化了RESTful API的设计和文档编写工作。RESTful API 有如下三个特点:

  • 资源的定位：RESTful API 将数据和操作转化为资源和 HTTP 动词，使用 URI 定位资源。
  • 表现层状态转换：RESTful API 将资源状态作为响应数据的一部分，客户端通过修改资源状态来实现状态转换。
  • 无状态：RESTful API 不保存客户端的状态信息，客户端每次请求都需要提供完整的请求信息。

二、最佳实践和示例

1.使用HTTP动词来表达操作

增: 使用POST方法创建新的资源。
删: 使用DELETE方法删除存在的资源。
改: 使用PUT或PATCH方法来更新已存在的资源。
查: 使用GET方法读取资源。

1
2
3
4
5
// 示例如下：
GET /users/1
POST /users
PUT /users/1
DELETE /users/1

2.使用动词进行操作

有时对API调用的响应不涉及资源（如计算、转义或变换）。

1
2
3
4
5
6
7
8
9
// 示例如下：
// 读取
GET /translate?from=de_DE&to=en_US&text=Hallo
GET /calculate?para2=23&para2=432
// 触发更改服务器端状态的操作
POST /restartServer
// 无消息体
POST /banUserFromChannel
{ "user": "123", "channel": "serious-chat-channel" }

3.使用名词来表示资源

RESTful API 中应该使用名词来表示资源，而不是动词，以避免歧义和混淆。

1
2
3
// 示例如下：
GET /users/1
GET /orders/1

4.使用一致的复数名词来表达资源

1
2
3
// 示例如下：
GET /stories
GET /stories/3

5.使用查询参数来过滤和分页

RESTful API 应该使用查询参数来过滤和分页资源。

1
2
3
// 示例如下：
GET /users?gender=male
GET /users?page=1&pageSize=10

6：使用HTTP状态码来表示请求结果

RESTful API 应该使用HTTP状态码来表示请求结果，以便客户端能够根据状态码进行处理。

1
2
3
4
5
6
7
8
9
10
11
// 示例如下：
200：请求成功。
201：资源创建成功
301：永久移动。请求的资源已被永久的移动到新URI，返回信息会包括新的URI，浏览器会自动定向到新URI。今后任何新的请求都应使用新的URI代替
304：未修改。所请求的资源未修改，服务器返回此状态码时，不会返回任何资源。客户端通常会缓存访问过的资源，通过提供一个头信息指出客户端希望只返回在指定日期之后修改的资源
400：请求参数错误
401：未授权访问证
403：表示禁止访问资源
404：表示未找到资源。可设置”您所请求的资源无法找到”的提示页面
410：客户端请求的资源已经不存在。410不同于404，如果资源以前有现在被永久删除了可使用410代码，网站设计人员可通过301代码指定资源的新位置
500：服务器内部错误，无法完成请求

注：不要过度使用404。状态码的使用要尽量精确：如果资源可用，但禁止用户访问，则返回403；如果资源曾经存在但现已被删除或停用，则返回410。

7.提供有用的错误消息

除了提供恰当的HTTP状态代码外，还应该在HTTP响应正文中提供有用且详细的错误描述。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
// 示例如下：
// 请求
GET /epics?state=unknow
// 响应：400错误
{
  "errors": [
    {
      "status": 400,
      "detail": "Invalid state. Valid values are 'biz' or 'tech'",
      "code": 352,
      "links": {
        "about": "http://www.jira.com/rest/errorcode/352"
      }
    }
  ]
}

8.使用 HATEOAS 来提高 API 的可发现性

HATEOAS（Hypermedia As The Engine Of Application State），是指使用超媒体作为应用程序状态的引擎。其原则就是客户端与服务器的交互完全由超媒体动态提供，客户端无需事先了解如何与数据或者服务器交互。通过使用HATEOAS，客户端可以通过API返回的链接自主地遍历API，并进行资源的操作。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// 示例如下：
GET /users/1
{
  "id": 1,
  "name": "Tom",
  "age": 25,
  "links": [
    {
      "rel": "orders",
      "href": "/users/1/orders"
    },
    {
      "rel": "edit",
      "href": "/users/1/edit"
    }
  ]
}

9.使用JSON或XML来表示数据

RESTful API 应该使用JSON或XML来表示数据，以便不同的客户端能够方便地进行数据解析和处理。

1
2
3
4
5
6
7
// 示例如下：
GET /users/1
{
  "id": 1,
  "name": "Tom",
  "age": 25
}

10.使用小驼峰命名法来命名属性

1
2
// 示例如下：
{ "epic.dateOfCreated": 2019-05-16 }

三、RESTful API 未来的发展方向

  • 支持更多的协议和数据格式，如gRPC、GraphQL等。
  • 增强API的安全性和稳定性，包括OAuth2认证、HTTPS协议等。
  • 支持更多的语言和框架，使得 RESTful API 可以更加广泛地应用于不同的开发环境中。
  • 支持自动化工具，如Swagger、Postman等，以便更加方便地进行API的设计、文档编写和测试。