RESTful架构（Representational State Transfer，资源表现层状态转换）

一：RESTful的架构

      1.

        （1）它是一种架构设计思想，而非技术。

        （2）概述：起源：REST这个词，是Roy Thomas Fielding在他2000年的博士论文中提出的。

                他是这样介绍的：

                "本文研究计算机科学两大前沿----软件和网络----的交叉点。长期以来，软件研究主要关注软件设计的分类、设计

                方法的演化，很少客观地评估不同的设计选择对系统行为的影响。而相反地，网络研究主要关注系统之间通信行

                为的细节、如何改进特定通信机制的表现，常常忽视了一个事实，那就是改变应用程序的互动风格比改变互动协

                议，对整体表现有更大的影响。我这篇文章的写作目的，就是想在符合架构原理的前提下，理解和评估以网络为基

                础的应用软件的架构设计，得到一个功能强、性能好、适宜通信的架构。"

    2.

       （1）定义：如果一个架构符合REST原则，就称它为RESTful架构。

       （2）资源：所谓"资源"，就是网络上的一个实体，或者说是网络上的一个具体信息。它可以是一段文本、一张图片、

                一首歌曲、一种服务等等。你可以用一个URI（统一资源定位符）指向它，每种资源对应一个特定的URI。要获

                取这个资源，访问它的URI就可以，因此URI就成了每一个资源的地址或独一无二的识别符。

              URI只代表资源的实体，不代表它的形式。严格地说，有些网址最后的".html"后缀名是不必要的，因为这个后缀

              名表示格式，属于"表现层"范畴，而URI应该只代表"资源"的位置。它的具体表现形式，应该在HTTP请求的头信

              息中用Accept和Content-Type字段指定，这两个字段才是对"表现层"的描述。

      （3）表现层：我们把"资源"具体呈现出来的形式，叫做它的"表现层"。例如，文本可以用txt格式表现，也可以用

              HTML格式、XML格式、JSON格式表现，甚至可以采用二进制格式； 图片可以用JPG格式表现，也可以用PNG

              格式表现。

     （4）状态转化（State Transfer）

                    访问一个网站，就代表了客户端和服务器的一个互动过程。在这个过程中，势必涉及到数据和状态的变化。互联

            网通信协议HTTP协议，是一个无状态协议。这意味着，所有的状态都保存在服务器端。因此，如果客户端想要操作服

            务器，必须通过某种手段，让服务器端发生"状态转化"（State Transfer）。而这种转化是建立在表现层之上的，所以

            就是"表现层状态转化"。

                   客户端用到的手段，只能是HTTP协议。具体来说，就是HTTP协议里面，四个表示操作方式的动词：GET、POST、

           PUT、DELETE。它们分别对应四种基本操作：GET用来获取资源，POST用来新建资源（也可以用于更新资源），PUT

           用来更新资源，DELETE用来删除资源。

二：RESTful风格Api

      1.RESTful api接口规范：

     （1）协议

             API与用户的通信协议，总是使用HTTPs协议，确保交互数据的传输安全。

     （2）域名应该尽量将API部署在专用域名之下。

             https://api.example.com

             如果确定API很简单，不会有进一步扩展，可以考虑放在主域名下。

             https://example.org/api/

     （3）api版本控制

             应该将API的版本号放入URL。

             https://api.example.com/v{n}/

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

            采用多版本并存，增量发布的方式。

            v{n} n代表版本号,分为整形和浮点型；

            整形的版本号: 大功能版本发布形式；具有当前版本状态下的所有API接口 ,例如：v1,v2；

            浮点型：为小版本号，只具备补充api的功能，其他api都默认调用对应大版本号的api 例如：v1.1 v2.2

     （4）API 路径规则

              路径又称"终点"（endpoint），表示API的具体网址。在RESTful架构中，每个网址代表一种资源（resource），所以

              网址中不能有动词，只能有名词，而且所用的名词往往与数据库的表格名对应。一般来说，数据库中的表都是同种记

              录的"集合"（collection），所以API中的名词也应该使用复数。

              举例来说，有一个API提供动物园（zoo）的信息，还包括各种动物和雇员的信息，则它的路径应该设计成下面这样。

              https://api.example.com/v1/products

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

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

     （5）HTTP请求方式

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

              常用的HTTP动词有下面四个（括号里是对应的SQL命令）。

             GET（SELECT）：从服务器取出资源（一项或多项）。

             POST（CREATE）：在服务器新建一个资源。

             PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。

             DELETE（DELETE）：从服务器删除资源。

            下面是一些例子。

             GET /product/ID/purchase ：列出某个指定商品的所有投资者

             GET /product/ID/purchase/ID：获取某个指定商品的指定投资者信息

             GET /product：列出所有商品

             GET /product/ID：获取某个指定商品的信息

             POST /product：新建一个商品

             PUT /product/ID：更新某个指定商品的信息

             DELETE /product/ID：删除某个商品

    （6）过滤信息

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

             下面是一些常见的参数。

             ?limit=10：指定返回记录的数量

             ?offset=10：指定返回记录的开始位置。

             ?page=2&per_page=100：指定第几页，以及每页的记录数。

             ?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。

             ?producy_type=1：指定筛选条

   （7）API 传入参数

            参入参数分为4种类型：

            （a）地址栏参数

                     restful 地址栏参数 /api/v1/product/122 122为产品编号，获取产品为122的信息

                     get方式的查询字串 见过滤信息小节

           （b）请求body数据

                    cookie

                    request header

                    cookie和header 一般都是用于OAuth认证的2种途径

           （c）返回数据

                    只要api接口成功接到请求，就不能返回200以外的HTTP状态。

                    为了保障前后端的数据交互的顺畅，建议规范数据的返回，并采用固定的数据格式封装。

                    接口返回模板：

            {

                status:0,

                data:{}||[],

                msg:’’
            }

                    status：接口的执行的状态

                                =0表示成功

                                <0 表示有异常=""

                    Data：接口的主数据，可以根据实际返回数组或JSON对象。

                    Msg：当status!=0 都应该有错误信息。