设计一个RESTful 规则

Posted 2022-11-28 有且仅有

一、什么是RESTful

历史

Roy Thomas Fielding （菲尔丁） 是HTTP 协议的主要作者之一。它在2000年于加州大学艾尔文分校所做的博士毕业论文Architectural Styles and the Design of Network-based Software Architectures 中，描述了一种称为REST 的网络软件架构风格，目的是方便不同软件在网络中互相传递消息。

注意，REST 不是凭空创建出来的所谓「标准」，而只是基于现有HTTP 协议而提出的一种「简单和易于理解的架构风格」，如果大家都能使用这种风格则无疑会方便互联网中的HTTP 信息交互。

释义

REST - Representational State Transfer 意为「具象状态转移」, REST 并不好理解，不过当我们理解了网络信息交换的主体是「资源(Resource)」时，我们其实可以明白REST 说的是「资源的状态转移」。

ful 是形容词后缀表示「有…性质的」，可知RESTful 指：有具象状态转移性质的……。在Web 应用开发时，当我们设计了一个有具象状态转移性质的Web API 时，我们称之为RESTful API。

二、RESTful API 规则推荐

虽然REST 有6个指导性约束，但它不是协议更没有「官方标准」，所以参考了网络上若干解释后我约定如下规则：

1. 协议与域名

   协议使用HTTPS，域名使用专用于API 的域名，例如：

   https://api.ddupa.com

2. 版本

   虽然Roy Thomas Fielding 认为设计良好的API 不应该有版本这个概念，因为这增加了客户端的理解难度，还会有潜在的服务升级后客户端不可用的风险。但基于业界通用做法，我们还是会使用版本，位置在域名之后，例如：

   https://api.ddupa.com/v1

3. 使用名词且用复数

   在RESTful 风格中，每个URL 代表一种资源（resource），亦即网址是对资源的静态描述，固只能用名词而禁用动词。另外，资源通常都是数据的「集合」，所以API 中的名词也应使用复数。

   举例来说，假设api.ddupa.com 的学校（school）模块提供了管理员可管理信息的接口，包括学生和课程，则它应被设计成如下格式：

   https://api.ddupa.com/v1/school/students

   https://api.ddupa.com/v1/school/courses

4. HTTP 的动词

   目前为止我们只定义了静态的资源，接下来我们为了使其发生「状态转移」必须使用HTTP 的动词来达成目的。

   HTTP 动词有很多，我们约定使用如下几种即能满足我们的需求：

   GET : 从服务器获取资源（一个或多个）。

   POST : 在服务器新建一个资源。

   PUT : 更新服务器的资源（客户端提供的所有属性将被使用，例如name:null将使服务器将name属性值设置为null）。

   PATCH : 更新服务器的资源（客户端仅提供改变的属性即可，null属性将被忽略，例如name:null将被服务器忽略）。

   DELETE : 从服务器删除资源。

   举例如下：

   GET /courses/id : 获取id代表的课程。

   GET /courses/pages : 获取课程的某一页（一页包含多个课程）。

   POST /courses : 新建一个课程。

   PUT /courses/id : 更新id代表的课程的全部信息。

   PATCH /courses/id : 更新id代表的课程的部分信息。

   DELETE /courses/id : 删除课程。

5. GET 的信息过滤

   获取资源时通常我们只对有某些特征的资源感兴趣，所以API 应该提供参数，用以过滤结果。

   例如：

   ?limit=10 : 指定返回资源数量。

   ?offset=10 : 指定返回资源开始位置。

   ?pageNo=3&pageSize=20 : 指定页码和每页记录数。

   ?sortby=createTime&order=desc : 指定排序规则和顺序。

   ?type=1 : 指定返回type为1的资源。

6. Request 数据格式约定

   • 路径参数

     所有HTTP 方法均可用，在URL 路径参数部分中，例如/id。

   • 查询参数

     GET 方法可用，在URL 中查询参数部分，例如?type=1。

   • 请求体

     POST/PUT/PATCH 方法可用，在Request Body 部分，且必须是Content-Type : application/json;charset=UTF-8。

7. Response 约定

   HTTP 状态码如：200, 404, 500等当然应该被使用，除此之外我们还应该定义一个统一的响应格式，内容类型为Content-Type : application/json;charset=UTF-8，例如：

   
     "state": 1,
     "message": "操作成功/操作失败",
     "content": 
       "data": 
     
   

三、参考

规则

• Architectural Styles and the Design of Network-based Software Architectures
• wikipedia
• RESTful API 设计指南

实例

• GitHub REST API
• OpenStack Clustering API