01restful规范

resutful规范

一、介绍

Restful（Representational State Transfer）是一种软件架构风格，它定义了一组规范和约束，用于设计可伸缩、可维护和易于集成的分布式系统。
Restful 架构的核心概念是资源（Resource）和资源的表述（Representation）。
- 资源是指系统中的任何信息，可以是一个文档、图像、视频、数据库记录等。
- 每个资源都有唯一的标识符（URI，Uniform Resource Identifier）用于定位和访问资源。
Restful 架构中，客户端通过HTTP协议向服务器发送请求，并根据不同的HTTP方法（GET、POST、PUT、DELETE等）执行不同的操作。

二、规范注意

【1】https协议

建议使用https协议替代http协议，让接口数据更加安全。

如果是基于HTTP协议，则意味着用户浏览器再向服务器发送数据时，都是以明文的形式传输，如果你在某咖啡厅上网，他就可以把你网络传输的数据明文都获取到。

如果是基于HTTPS协议，则意味着用户浏览器再向服务器发送数据时，都是以密文的形式传输，中途即使有非法用户获取到网络数据，也可以密文的，无法破译。

HTTPS保证了数据安全，但由数据传输存在着加密和解密的过程，所以会比HTTP协议慢一些。

【2】域名

对于后端API接口中要体现API标识，例如：

https://api.example.com
https://www.example.com/api/

【3】版本

对于后端API接口中要体现版本，例如：

- http://api.example.com/v1/

- http://api.example.com/?version=v1

- http://v1.example.com/

【4】路径

restful API这种风格中认为网络上的一切都称是资源，围绕着资源可以进行增删改查等操作。

这些资源，在URL中要使用名词表示（可复数），围绕着资源进行的操作就用Method不同进行区分。

https://api.example.com/v1/person
https://api.example.com/v1/zoos
https://api.example.com/v1/animals
https://api.example.com/v1/employees

【5】请求方法

根据请求方法不同进行不同的操作

GET
- 在服务区获取资源（一项或多项）
- 可通过URL参数传递过滤、排序等条件
POST
- 在服务器新建一个资源
- 客户端将资源表述作为请求体发给服务器
PUT
- 在服务器更新资源（客户端提供改变后的完整资源）
- 将客户端更新后的数据作为请求题发送给服务器
DELETE
- 在服务器删除资源
- 客户端发送一个请求，指定要删除资源
PATCH
- 在服务器更新资源（客户端提供改变的属性）

示例：

https://api.example.com/v1/users
https://api.example.com/v1/users/1/

接口：/users/			方法：GET     =>   用户列表
接口：/users/			方法：POST    =>   添加用户
接口：/users/(\d+)/	方法：GET     =>   获取单条数据
接口：/users/(\d+)/	方法：DELETE  =>   删除数据
接口：/users/(\d+)/	方法：PUT     =>   更新数据
接口：/users/(\d+)/	方法：PATCH   =>   局部更新

【6】搜索条件

在URL中通过参数的形式来传递搜索条件。

https://api.example.com/v1/zoos?limit=10				指定返回记录的数量
https://api.example.com/v1/zoos?offset=10				指定返回记录的开始位置
https://api.example.com/v1/zoos?page=2&per_page=100		指定第几页，以及每页的记录数
https://api.example.com/v1/zoos?sortby=name&order=asc	指定返回结果按照哪个属性排序，以及排序顺序
https://api.example.com/v1/zoos?animal_type_id=1		指定筛选条件

【7】返回数据

针对不同操作，服务器向用户返回的结果结构应该不同。

https://api.example.com/v1/users
https://api.example.com/v1/users/2/

URL	方法	描述	返回数据
/users/	GET	列表	返回资源对象的列表 [ {id:1,name:"serein"}, {id:1,name:"日天"} ]
/users/	POST	添加	返回新生成的资源对象
/users/(\d+)/	GET	获取单条数据	返回单个资源对象
/users/(\d+)/	DELETE	删除数据	返回一个空文档 null
/users/(\d+)/	PUT	更新数据	返回完整的资源对象
/users/(\d+)/	PATCH	局部更新	返回完整的资源对象

一般在实际的开发过程中会对上述返回数据进行补充和完善，例如：每次请求都返回一个字典，其中包含：

code，表示返回码，用于表示请求执行请求，例如：0表示请求成功，1003表示参数非法，40009数据量太大等。
data，表示数据
error，错误信息

【8】状态码

后端API在对请求进行响应时，除了返回数据以外还可以返回状态码，来表示请求状况。

200 OK - [GET]：服务器成功返回用户请求的数据
201 CREATED - [POST/PUT/PATCH]：用户新建或修改数据成功。
202 Accepted - [*]：表示一个请求已经进入后台排队（异步任务）
204 NO CONTENT - [DELETE]：用户删除数据成功。
400 INVALID REQUEST - [POST/PUT/PATCH]：用户发出的请求有错误，服务器没有进行新建或修改数据的操作。
401 Unauthorized - [*]：表示用户未认证（令牌、用户名、密码错误）。
403 Forbidden - [*] 表示用户得到授权（与401错误相对），但是访问是被禁止的。
404 NOT FOUND - [*]：用户发出的请求针对的是不存在的记录，服务器没有进行操作。
406 Not Acceptable - [GET]：用户请求的格式不可得（比如用户请求JSON格式，但是只有XML格式）。
410 Gone -[GET]：用户请求的资源被永久删除，且不会再得到的。
422 Unprocesable entity - [POST/PUT/PATCH] 当创建一个对象时，发生一个验证错误。
500 INTERNAL SERVER ERROR - [*]：服务器发生错误，用户将无法判断发出的请求是否成功。

【9】错误处理

错误处理，状态码是4xx时，应返回错误信息，error当做key。

{
    error: "Invalid API key"
}

总结

1 数据的安全保障：url链接一般都采用https协议进行传输
    	-https是：http+ssl 安全的超文本传输协议
    2 接口特征表现：在API地址中带接口标识，咱们一般放在地址栏中(放在域名中)
        https://api.baidu.com
        https://www.baidu.com/api
        
   3 多版本共存：在url链接中带版本标识
		-https://api.weibo.com/2/
    	-https://api.weibo.com/v2/
        -https://api.weibo.com/?version=2
        -https://api.weibo.com/v1/login  --->需要的参数name和pwd
        -https://api.weibo.com/v2/login --->需要的参数name和pwd和code
        
  4 数据即是资源，均使用名词（可复数）：前后端交互的数据我们称之为资源
	-资源名都是名词,尽量避免使用动词
    -https://127.0.0.1/api/v1/users
    -https://127.0.0.1/api/v1/get_users  # 不符合规范
  5 资源操作由请求方式决定（method）	
	-获取资源用get
    -新增资源用post
    -修改资源使用put
    -删除资源使用delete
    https://api.baidu.com/books      - get请求：获取所有书
    https://api.baidu.com/books/1    - get请求：获取主键为1的书
    https://api.baidu.com/books      - post请求：新增一本书书
    https://api.baidu.com/books/1    - put请求：整体修改主键为1的书
    https://api.baidu.com/books/1    - patch请求：局部修改主键为1的书
    https://api.baidu.com/books/1    -delete请求：删除主键为1的书
    
 6 url中带搜索或过滤条件
	https://api.example.com/v1/zoos?name=猴子 get请求 
    
 7 响应状态码：响应中带状态码
	-http响应状态码：1xx，2xx，3xx，4xx，5xx
    -自己的状态码（用的多）： 100成功，看公司自己
        错误代码	错误信息	详细描述
        10001	System error	系统错误
        10002	Service unavailable	服务暂停
        10003	Remote service error	远程服务错误
        10004	IP limit	IP限制不能请求该资源
        10005	Permission denied, need a high level appkey	该资源需要appkey拥有授权
        
8 返回中带错误信息
	{code:100,msg:成功}
    "Message": "send success",
    
9 返回结果，符合以下规范
	GET /collection：返回资源对象的列表（数组）       [{name:xx,age:19},{name:xx,age:19},{}]
    GET /collection/resource：返回单个资源对象        {name:xx,age:19}
    POST /collection：返回新生成的资源对象             {name:yy,age:19}
    PUT /collection/resource：返回完整的资源对象       {name:xx,age:20}
    PATCH /collection/resource：返回完整的资源对象     {name:xx,age:20}
    DELETE /collection/resource：返回一个空文档        
10 返回数据中带url链接
	  "url": "http://blog.sina.com.cn/zaku",

posted @ 2024-05-15 16:43 Formerly0^0 阅读(30) 评论(0) 收藏举报

刷新页面返回顶部

Formerly