Restful API接口规范

Restful API概念

RESTful API 是应用程序接口 (API) 的一种架构风格，它使用 HTTP 请求来访问和使用数据。该数据可用于 GET、PUT、POST 和 DELETE 数据类型，这些数据类型是指有关资源的操作的读取、更新、创建和删除。

http方法

使用RESTful风格的接口，从接口上可能只能定位其资源，但是无法知晓它具体进行了什么操作，需要具体了解其发生了什么操作动作要从其HTTP请求方法类型上进行判断。具体的HTTP方法和方法含义如下：

• GET（SELECT）： 从服务器取出资源（一项或多项）。
• POST（CREATE）： 在服务器新建一个资源。
• PUT（UPDATE）： 在服务器更新资源（客户端提供完整资源数据）。
• PATCH（UPDATE）： 在服务器更新资源（客户端提供需要修改的资源数据）。
• DELETE（DELETE）： 从服务器删除资源。

设计规范

1. 使用http method动作表示操作

操作应该使用 HTTP 动词来表达，例如 GET（获取资源）、POST（创建资源）、PUT（更新资源）、DELETE（删除资源） 等，以确保对资源的操作被明确表示和限制。如下所示：

GET /users           # 获取用户列表
GET /users/{id}      # 获取单个用户
POST /users          # 创建新用户
PUT /users/{id}      # 更新用户信息
DELETE /users/{id}   # 删除用户

不能使用crud的操作在uri中。例如：getUsers、createUser、findUsers、addUsers、updateUsers、deleteUsers等。

2. 使用名称表示资源

在URI中使用名词来表示资源，而不是动词，以避免歧义和混淆。对于表示资源集合的URI，通常使用复数形式，以便明确表示这是一个集合而不是单个资源。例如：

# 推荐
/users						# 用户资源
/orders						# 订单资源

# 避免
/user
/order

3. 使用uri来定位资源
   restful api应该使用uril定位资源，以确保每一个资源都有一个唯一的标识符。uri应该具有层级结构，以便表示资源之间的关系。例如：

GET /users/1/orders/1

表示user==1 && orders ==1

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

获取前10个用户：		GET /users?limit=10
获取第二页的用户：		GET /users?page=2&limit=10

使用查询参数来过滤和分页资源，例如：“?page=1 & limit=10”

5.使用 HTTP 状态码来表示请求结果

使用 合适的HTTP 状态码来表示请求结果，以便客户端能够根据状态码进行处理。例如：。状态码主要分为五大类：

1xx：相关信息
2xx：操作成功
3xx：重定向
4xx：客户端错误
5xx：服务器错误

例如：

• 200：请求成功
• 201：资源创建成功
• 400：请求参数错误
• 401：未授权访问
• 403：表示禁止访问资源。
• 404：表示未找到资源。
• 500：表示服务器内部错误。

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

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

GET /users/1
{
  "id": 1,
  "name": "Tom",
  "age": 25
}

7. 使用版本号来管理 API

RESTful API 应该使用版本号来管理 API 的不同版本，以便支持旧版 API 的兼容性和平稳升级。应该将API的版本号放入URL。 版本号以字符'v'开头，比如：v1、v2

(未完，待续)