restful规范

一、restful介绍

1、web服务交互

　　网站提供的每个web服务都需要前后端交互，前后端交互的实现方案，通常叫作：web服务交互方案。

（1）目前主流的三种web服务交互方案

　　1）REST（Representational State Transgfer）表述性状态转移

　　REST是Roy Thomas Fielding博士于2000年在他的博士论文里提出来的。

　　REST相比SOAP更加简洁，性能和开发效率也有突出的优势。

　　2）SOAP（Simple Object Access Protoco）简单的对象访问协议

　　SOAP服务则是以本身所定义的操作集，来访问网络上的资源。

　　SOAP也是基于XML的，但是它不只限于HTTP协议的传输，包括TCP协议，UDP协议都可以传输。

　　3）XML-RPC（XML Remote Procedure Call）基于XML的远程过程调用

　　XML-RPC是通过XML将调用函数封装，并使用HTTP协议作为传送机制。后来在新的功能不断被引入下，这个标准慢慢演变成为今日的SOAP协定。

2、理解REST

　　REST与技术无关，代表的是一种软件架构风格，REST是Representational State Transfer的简称，中文翻译为“表征状态转移”。

　　这里说的表征性，其实就是资源。通常称为资源状态转移。

（1）什么是资源

　　什么事物，只要有被引用的必要，它就是一个资源。资源可以是一个实体，也可以是抽象概念。

　　实体资源很好理解，个人信息、手机号、视频、图片等等都是实实在在存在的实体。而两个人的关系则是抽象的概念。

　　在网络中要引用资源，资源一定要有一个标识，在web中唯一标识就是URI。

（2）什么是URI和URL

　　URI：统一资源标志符（类似身份证号）。URL：统一资源定位符（类似家庭住址）。

　　URI是给资源进行标识的，URL是描述资源地址的。

　　通过这两种方式都可以找到我们的资源，其实URL可以说是URI的子集，通过定位的方式实现的URI。

（3）统一资源接口

　　获得URL后，可以通过URL去访问到资源，但对资源会有很多不同的操作（增删改查）。之前的方式是分别设计一个新的URL来对数据进行操作。

　　现在只需要一个URL，根据HTTP请求方式不同，对资源进行不同的操作，这就是统一资源接口。

（4）资源的表述

　　资源的表述其实就是资源的展现形式，客户端和服务端传输的都是资源的表述，而不是资源本身。

　　例如文本资源可以采用html、xml、json等格式，图片可以使用PNG或JPG展现出来。

　　那么客户端如何知道服务端提供哪种表述形式呢?

　　可以通过HTTP内容协商，客户端可以通过Accept头请求一种特定格式的表述，服务端则通过Content-Type告诉客户端资源的表述形式。

　　这些资源的表述呈现在页面上，就是我们说的资源状态。

（5）状态转移

　　看页面的时候，从当前资源的表述(也可以说状态或者表现层)会跳转到其他的资源状态。

　　服务端通过超媒体告诉客户端当前状态有哪些后续状态可以进入。

　　这些类似"下一页"之类的链接起的就是这种推进状态的作用——指引你如何从当前状态进入下一个可能的状态。

（6）总结

REST与技术无关，代表的是一种软件架构风格，REST是Representational State Transfer的简称，中文翻译为“表征状态转移”
REST从资源的角度类审视整个网络，它将分布在网络中某个节点的资源通过URL进行标识，客户端应用通过URL来获取资源的表征，获得这些表征致使这些应用转变状态
所有的数据，不管是通过网络获取的还是操作（增删改查）的数据，都是资源，将一切数据视为资源是REST区别与其他架构风格的最本质属性
对于REST这种面向资源的架构风格，有人提出一种全新的结构理念，即：面向资源架构（ROA：Resource Oriented Architecture）。

3、什么是restful

　　如果一个架构符合REST的约束条件和原则，我们就称它为RESTful架构。一种软件的架构风格，设计风格, 为客户端和服务端的交互提供一组设计原则和约束条件。

　　理解RESTful架构：http://www.ruanyifeng.com/blog/2011/09/restful.html

二、RESTful API设计

1、协议

　　API与用户的通信协议，总是使用HTTPs协议。

2、域名

https://api.example.com 尽量将API部署在专用域名（会存在跨域问题）
https://example.org/api/ API很简单（如果确定API很简单，不会有进一步扩展，可以考虑放在主域名下）

3、版本（Versioning）

　　应该将API的版本号放入URL。另一种做法是，将版本号放在HTTP头信息中，但不如放入URL方便和直观。Github采用这种做法。

URL，如：https://api.example.com/v1/
请求头

4、路径（Endpoint）

路径又称"终点"（endpoint），表示API的具体网址。

在RESTful架构中，每个网址代表一种资源（resource），所以网址中不能有动词，只能有名词，而且所用的名词往往与数据库的表格名对应。一般来说，数据库中的表都是同种记录的"集合"（collection），所以API中的名词也应该使用复数。

视网络上任何东西都是资源，均使用名词表示（可复数）

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

5、method（HTTP动词）

对于资源的具体操作类型，由HTTP动词表示。

常用的HTTP动词有下面五个，后面是对应的SQL命令。

GET ：从服务器取出资源（一项或多项） --SELECT
POST ：在服务器新建一个资源 --CREATE
PUT ：在服务器更新资源（客户端提供改变后的完整资源）--UPDATE
PATCH ：在服务器更新资源（客户端提供改变的属性） --UPDATE
DELETE ：从服务器删除资源 --DELETE

还有两个不常用的HTTP动词：

HEAD : 获取资源的元数据。
OPTIONS: 获取信息，关于资源的哪些属性是客户端可以改变的。

示例：

GET /zoos：列出所有动物园

POST /zoos：新建一个动物园

GET /zoos/ID：获取某个指定动物园的信息

PUT /zoos/ID：更新某个指定动物园的信息（提供该动物园的全部信息）

PATCH /zoos/ID：更新某个指定动物园的信息（提供该动物园的部分信息）

DELETE /zoos/ID：删除某个动物园

GET /zoos/ID/animals：列出某个指定动物园的所有动物

DELETE /zoos/ID/animals/ID：删除某个指定动物园的指定动物

6、过滤信息（Filtering）

如果记录数量很多，服务器不可能都将它们返回给用户。API应该提供参数，过滤返回结果。

通过在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：指定筛选条件

参数的设计允许存在冗余，即允许API路径和URL参数偶尔有重复。比如，GET /zoo/ID/animals 与 GET /animals?zoo_id=ID 的含义是相同的。

7、状态码（Status Codes）

服务器向用户返回的状态码和提示信息，常见的有以下一些（方括号中是该状态码对应的HTTP动词）。

200 OK - [GET]：服务器成功返回用户请求的数据，该操作是幂等的（Idempotent）。
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 - [*]：服务器发生错误，用户将无法判断发出的请求是否成功。

更多看这里：http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html

8、错误处理（Error handling）

状态码是4xx时，应向用户返回错误信息，一般来说，返回的信息中将error作为键名，出错信息作为键值即可。

{
    error: "Invalid API key"
}

9、返回结果

针对不同操作，服务器向用户返回的结果应该符合以下规范。

GET /collection：返回资源对象的列表（数组）
GET /collection/resource：返回单个资源对象
POST /collection：返回新生成的资源对象
PUT /collection/resource：返回完整的资源对象
PATCH /collection/resource：返回完整的资源对象
DELETE /collection/resource：返回一个空文档

10、Hypermedia API

RESTful API最好做到Hypermedia，即返回结果中提供链接，连向其他API方法，使得用户不查文档，也知道下一步应该做什么。

比如，当用户向api.example.com的根目录发出请求，会得到这样一个文档。

{"link": {
  "rel":   "collection https://www.example.com/zoos",
  "href":  "https://api.example.com/zoos",
  "title": "List of zoos",
  "type":  "application/vnd.yourformat+json"
}}

上面代码表示，文档中有一个link属性，用户读取这个属性就知道下一步该调用什么API了。rel表示这个API与当前网址的关系（collection关系，并给出该collection的网址），href表示API的路径，title表示API的标题，type表示返回类型。

Hypermedia API的设计被称为HATEOAS。Github的API就是这种设计，访问api.github.com会得到一个所有可用API的网址列表。

三、resful 10大规范

　　首先restful是一种软件架构风格或者说是一种设计风格，并不是标准，它只是提供了一组设计原则和约束条件，主要用于客户端和服务器交互类的软件。

　　就像设计模式一样，并不是一定要遵循这些原则，而是基于这个风格设计的软件可以更简洁，更有层次，我们可以根据开发的实际情况，做相应的改变。它里面提到了一些规范，例如:

1、尽量使用HTTPS

　　在url接口中推荐使用Https协议，让网络接口更加安全(Https是Http的安全版，即HTTP下加入 SSL层，HTTPS的安全基础是SSL，因此加密的详细内容就需要SSL(安全套接层协议))；

2、url中可以体现这是个API接口

　　https://www.bootcss.com/v1/mycss

　　https://v1.bootcss.com/mycss

3、url中还可以体现版本号

　　https://www.bootcss.com/v1/mycss

　　https://v1.bootcss.com/mycss

　　不同的版本可以有不同的接口，使其更加简洁，清晰。

4、面向对象编程

　　restful 提倡面向资源编程，所以在url接口中尽量要使用名词，不要使用动词。

5、url中体现过滤条件

　　添加条件去筛选匹配：

　　https://www.bootcss.com/v1/mycss?page=3

6、根据method不同，进行不同的操作

　　可以根据Http不同的method，进行不同的资源操作(5种方法:GET / POST / PUT / DELETE/ PATCH)

7、响应时应包含状态码

　　可以通过状态码直接判断服务器的响应信息。

　　1** 信息，服务器收到请求，需要请求者继续执行操作

　　2** 成功，操作被成功接收并处理

　　3** 重定向，需要进一步的操作以完成请求

　　4** 客户端错误，请求包含语法错误或无法完成请求

　　5** 服务器错误，服务器在处理请求的过程中发生了错误

8、返回值

　　应该有返回值，而且格式为统一的json格式。

　　GET请求返回查到所有或单条数据

　　POST请求返回新增的数据

　　PUT请求返回更新数据

　　PATCH请求局部更新返回更新整条数据

9、返回错误信息

　　返回值携带错误信息。

10、Hypermedia API（超链接）

　　如果遇到需要跳转的情况，携带跳转接口的URL。

　　返回结果中要提供帮助链接，即API最好做到Hypermedia。

ret = {
    code: 1000,
    data:{
        id:1,
        name:'小强',
        depart_id:http://www.luffycity.com/api/v1/depart/8/
    }
}

四、rest framework框架的10大组件

1、路由

可以通过as_view传参数，根据请求方式不同执行相应的方法
可以在url中设置一个结尾，类似于: .json

2、视图

帮助开发者提供了一些类，并在类中提供了多个方法以供我们使用。

3、版本

在url中设置version参数，用户请求时候传入参数。在request.version中获取版本，根据版本不同做不同处理

4、认证　　

写一个类并注册到认证类，在类的的authticate方法中编写认证逻辑。
- 认证成功(user,auth)
- raise AuthticateFaild(....)
- None

5、权限

写一个类并注册到权限类，在类的的has_permission方法中编写认证逻辑。
- True
- False

6、频率限制

写一个类并注册到频率类，在类的的 allow_request/wait 方法中编写认证逻辑。
allow_request
- True
- False 如果返回False，那么就要执行wait

7、解析器

根据ContentType请求头，选择不同解析器对请求体中的数据进行解析。
- POST /index/ http1.1.\r\nhost:11.11.11.11\r\nContent-Type:url-formendo....\r\n\r\nuser=alex&age=123
- POST /index/ http1.1.\r\nhost:11.11.11.11\r\nContent-Type:application/json\r\n\r\n{....}

8、分页

对从数据库中获取到的数据进行分页处理: SQL -> limit offset
- 根据页码:http://www.luffycity.com/api/v1/student/?page=1&size=10
- 根据索引:http://www.luffycity.com/api/v1/student/?offset=60&limit=10
- 根据加密:http://www.luffycity.com/api/v1/student/?page=erd8
问题:为什么页码越大速度越慢，以及如何解决?
原因:页码越大向后需要扫描的行数越多，因为每次都是从0开始扫描。
解决:
- 限制显示的页数
- 记录当前页数据ID最大值和最小值，再次分页时，根据ID现行筛选，然后再分页。

9、序列化

对queryset序列化以及对请求数据格式校验。

10、渲染器

根据URL中传入的后缀，决定数据如何渲染到到页面上。

五、rest-framework参考博客

rest-framework框架的基本组件

Django Rest Framework

Django-rest-framework官网

posted @ 2018-09-07 01:28 休耕阅读(379) 评论(0) 编辑收藏举报

刷新页面返回顶部

休耕

restful规范

一、restful介绍

1、web服务交互

（1）目前主流的三种web服务交互方案

2、理解REST

（1）什么是资源

（2）什么是URI和URL

（3）统一资源接口

（4）资源的表述

（5）状态转移

（6）总结

3、什么是restful

二、RESTful API设计

1、协议

2、域名

3、版本（Versioning）

4、路径（Endpoint）

5、method（HTTP动词）

6、过滤信息（Filtering）

7、状态码（Status Codes）

8、错误处理（Error handling）

9、返回结果

10、Hypermedia API

三、resful 10大规范

1、尽量使用HTTPS

2、url中可以体现这是个API接口

3、url中还可以体现版本号

4、面向对象编程

5、url中体现过滤条件

6、根据method不同，进行不同的操作

7、响应时应包含状态码

8、返回值

9、返回错误信息

10、Hypermedia API（超链接）

四、rest framework框架的10大组件

1、路由

2、视图

3、版本

4、认证

5、权限

6、频率限制

7、解析器

8、分页

9、序列化

10、渲染器

五、rest-framework参考博客

公告

4、认证　　