RESTful规范
什么是RESTful?
Representational State Transfer , 中文翻译为“表征状态转移” 。
Resource(资源): 对象的单个实例,是一个具体的实在。可以用一个URI(统一资源定位符)指向它,每种资源对应一个特定的URI。要获取这个资源,访问它的URI就可以,因此URI就成了每一个资源的地址或独一无二的识别符。
表现层(Representation) :"资源"是一种信息实体,它可以有多种外在表现形式。我们把"资源"具体呈现出来的形式,叫做它的"表现层"(Representation)。
状态转化(State Transfer) : 互联网通信协议HTTP协议,是一个无状态协议。这意味着,所有的状态都保存在服务器端。因此,如果客户端想要操作服务器,必须通过某种手段,让服务器端发生"状态转化"(State Transfer)。 客户端用到的手段,只能是HTTP协议。 就是在HTTP协议里面,用四个表示操作方式的动词: GET、POST、PUT、DELETE。它们分别对应四种基本操作:GET用来获取资源,POST用来新建资源(也可以用于更新资源),PUT用来更新资源,DELETE用来删除资源。
所有的数据,不过是通过网络获取的数据,都是资源,将一切数据视为资源是REST区别与其他架构风格的最本质属性。
对于REST这种面向资源的架构风格,有人提出一种全新的结构理念,即:面向资源架构(ROA:Resource Oriented Architecture)。
RESTful API设计规范
restful是一个API接口的规则,是程序进行数据交换的约定。
-
建议用https代替http,保证数据传输的安全。
-
在URL中体现api,添加api标识,
https://www.xxx.com/api/p/xxx/ # 建议,不存在跨域 https://api.xxx.com/p/xxx 版本还可以放在请求头。
-
在URL中体现版本(便于版本迭代)
https://www.xxx.com/api/v1/p/xxx/ # v1版本
-
restful是面向资源编程,网络上的一切都是资源,因此一般情况下对于api接口,用名词,不用动词。
https://www.xxx.com/api/v1/userinfo/
-
如果有加入筛选条件的话,可以在URL后面进行传递。
/?page=1&xxx=2
-
根据method不同做不同操作,之前使用4个URL,现在只需使用一个。
get/post/put/patch/delete GET :从服务器取出资源(一项或多项) POST :在服务器新建一个资源 PUT :在服务器更新资源(客户端提供改变后的完整资源) PATCH :在服务器更新资源(客户端提供改变的属性,局部更新) DELETE :从服务器删除资源
-
返回给用户状态码 200 301/302 400 500
data_info = {"code": 10001, 'data': random_string} return Response(data_info) # 常用状态码: 200 OK - [GET]:服务器成功返回用户请求的数据,该操作是幂等的(Idempotent)。 201 CREATED - [POST/PUT/PATCH]:用户新建或修改数据成功。 202 Accepted - [*]:表示一个请求已经进入后台排队(异步任务) 204 NO CONTENT - [DELETE]:用户删除数据成功。 301/302:永久重定向/临时重定向 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 - [*]:服务器发生错误,用户将无法判断发出的请求是否成功。
-
返回值, 针对不同操作,服务器向用户返回的结果应该符合以下规范。
GET /collection:返回资源对象的列表(数组) GET /collection/resource:返回单个资源对象 POST /collection:返回新生成的资源对象 PUT /collection/resource:返回完整的资源对象 PATCH /collection/resource:返回完整的资源对象 DELETE /collection/resource:返回一个空文档
-
操作异常,要返回错误信息, error当做key。
{error: 'Invalid API Key'}
-
Hypermedia API,RESTful API最好做到Hypermedia,即返回结果中提供链接,连向其他API方法,使得用户不查文档,也知道下一步应该做什么。
```
{"link": {
"rel": "collection https://www.example.com/zoos",
"href": "https://api.example.com/zoos",
"title": "List of zoos",
"type": "application/vnd.yourformat+json"
}}
```