RESTful风格

RESTful风格

1. 简单介绍

   REST（英文：，简称REST）描述了一个架构样式的网络系统，比如 web 应用程序。它首次出现在 2000 年 Roy Fielding 的博士论文中，Roy Fielding是 HTTP 规范的主要编写者之一。在目前主流的三种Web服务交互方案中，REST相比于SOAP（Simple Object Access protocol，简单对象访问协议）以及XML-RPC更加简单明了，无论是对URL的处理还是对Payload的编码，REST都倾向于用更加简单轻量的方法设计和实现。值得注意的是REST并没有一个明确的标准，而更像是一种设计的风格。

2. 原则条件

   REST 指的是一组架构约束条件和原则。满足这些约束条件和原则的应用程序或设计就是 RESTful。

   Web 应用程序最重要的 REST 原则是，客户端和服务器之间的交互在请求之间是无状态的。从客户端到服务器的每个请求都必须包含理解请求所必需的信息。如果服务器在请求之间的任何时间点重启，客户端不会得到通知。此外，无状态请求可以由任何可用服务器回答，这十分适合云计算之类的环境。客户端可以缓存数据以改进性能。

   在服务器端，应用程序状态和功能可以分为各种资源。资源是一个有趣的概念实体，它向客户端公开。资源的例子有：应用程序对象、数据库记录、算法等等。每个资源都使用 URI (Universal Resource Identifier) 得到一个唯一的地址。所有资源都共享统一的接口，以便在客户端和服务器之间传输状态。使用的是标准的 HTTP 方法，比如 GET、PUT、POST 和 DELETE。Hypermedia 是应用程序状态的引擎，资源表示通过超链接互联。

3. Restful风格设计-关键点

   1. URL路径

      URL地址尽量使用名词复数，不要使用动词。

      # 不好的例子
      /getProducts
      /listOrders
      
      # 正确的例子
      GET /products：将返回所有产品信息
      POST /products：将新建产品信息
      GET /products/4：将获取产品4
      PUT /products/4：将更新产品4
      

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

   2. 请求方式

      访问同一个URL地址，采用不同的请求方式，代表要执行不同的操作。

      常用的HTTP请求方式有下面四个：

      请求方式	说明
      GET	获取资源数据(单个或多个)
      POST	新增资源数据
      PUT	修改资源数据
      DELETE	删除资源数据

      例如：

      GET /books：列出所有图书数据
      POST /books：新建一本图书数据
      GET /books/<id>/：获取某个指定的图书数据
      PUT /books/<id>/：更新某个指定的图书数据
      DELETE /books/<id>/：删除某个指定的图书数据
      

   3. 过滤信息

      过滤参数可以放在查询字符串中。

      在访问API接口获取数据时，可能需要对数据进行过滤。

      常见的参数：

      ?limit=10：指定返回记录的数量
      ?offset=10：指定返回记录的开始位置。
      ?page=2&pagesize=100：指定第几页，以及每页的记录数。
      ?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。
      

   4. 响应数据

      针对不同操作，服务器向用户返回不同的响应数据。

      一般遵循以下规范：

      1. 获取一组数据，返回一组数据
      2. 获取指定数据，返回指定数据
      3. 新增数据，返回新增的数据
      4. 修改数据，返回修改的数据
      5. 删除数据，返回空
      

   5. 响应数据格式

      服务器返回的响应数据格式，应该尽量使用JSON。

   6. 响应状态码

      服务器向客户端返回的状态码和提示信息，常见的状态码如下：

      200 OK - [GET/PUT]：服务器成功返回用户请求的数据
      201 CREATED - [POST]：用户新建数据成功。
      204 NO CONTENT - [DELETE]：用户删除数据成功。
      400 INVALID REQUEST - [POST/PUT]：用户发出的请求有错误，服务器没有进行新建或修改数据的操作
      404 NOT FOUND - [*]：用户发出的请求针对的是不存在的记录，服务器没有进行操作，该操作是幂等的
      500 INTERNAL SERVER ERROR - [*]：服务器发生错误，用户将无法判断发出的请求是否成功。
      

      状态码的完全列表参见这里或这里。

4. Restful风格设计-其他

   1. 域名

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

      https://api.example.com
      

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

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

   2. 版本

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

      http://www.example.com/api/1.0/foo
      
      http://www.example.com/api/1.1/foo
      
      http://www.example.com/api/2.0/foo
      

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

   3. 错误处理

      如果状态码是4xx，服务器就应该向用户返回出错信息。

      {
          error: "<error message>"
      }
      

   4. 超媒体

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

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

      {
          "current_user_url": "https://api.github.com/user",
          "authorizations_url": "https://api.github.com/authorizations",
          // ...
      }
      

      从上面可以看到，如果想获取当前用户的信息，应该去访问api.github.com/user，然后就得到了下面结果。

      {
          "message": "Requires authentication",
          "documentation_url": "https://developer.github.com/v3"
      }
      

      上面代码表示，服务器给出了提示信息，以及文档的网址。

5. 总结

   要点
   url地址	url地址尽量使用名词复数，不要使用动词
   请求方式	执行不同的操作，采用不同的请求方式： GET(获取) POST(新增) PUT(修改) DELETE(删除)
   响应数据	获取多个数据时，返回对应的多个数据 获取单个数据时，返回对应的单个数据 新增数据时，将新增的数据返回 修改数据时，将修改的数据返回 删除数据时，返回空
   过滤参数	过滤参数放在查询字符串中
   响应数据格式	JSON
   响应状态码	200(获取或修改成功) 201(新增成功) 204(删除成功) 404(资源找不到) 500(服务器出错)