RESTful开发规范详解

什么是Restful

兴起于Rails。是一种优雅的URI表述方式，可以表示资源的状态和状态转移。

Fielding将他对互联网软件的架构原则，定名为REST，即 Resource Representational State Transfer的缩写。

如果一个架构符合REST原则，就称它为RESTful架构。

RESTful资源-Resource

• 文本
• 图片
• 服务
• 音频
• …

RESTful表现层-Representational

• 文本：txt、html、xml、json、二进制
• 图片：jpg、png
• http协议的content-type和accept(通过这个协议头指定表现形式)

RESTful状态转化-State Transfer

• 幂等性：每次HTTP请求相同的参数，相同的URI，产生的结果是相同的
• GET-获取资源
• POST-创建资源，不具有幂等性
• PUT-创建(更新)资源
• DELETE-删除资源

设计概念和准则

• 网络上的所有事物都可以被抽象为资源。
• 每一个资源有唯一的资源标识，对资源的操作不会改变这些标识。
• 所有的操作都是无状态的。

RESTful架构与其他架构的区别

SOAP WebService

WebService 是一种跨编程语言跨操作系统平台的远程调用技术。

WebService 通过HTTP协议发送请求和接收结果时XML格式封装，并增加了一些特定的HTTP消息头，这些特定的HTTP消息头和XML内容格式就是SOAP协议。

• 效率和易用性

SOAP由于各种需求不断扩充其本身内容，导致在SOAP处理方面的性能有所下降。同时在易用性方面以及学习成本上也有所增加。

• 安全性

RESTful对于资源型服务接口来说很适合，同时特别适合对于效率要求很高，但是对于安全性要求不高的场景。

SOAP的成熟性可以给需要提供给多开发语言的，对于安全性要求较高的接口设计带来便利。所以，什么设计模式将会占据主导地位，关键是看应用场景。

RESTful设计要素

1. 如何设计RESTful API
   • 资源路径(URI)

   在RESTful架构中，每个网址代表一种资源，所以网址中不能有动词，只能有名词。一般来说API中的名词应该复数。

   例如：一个API提供动物园(zoo)的信息，还包括各种动物和雇员的信息，则路径应该设计成如下所示：

https://api.example.com/v1/zoos  // 动物园资源

https://api.example.com/v1/animals  // 动物资源

https://api.example.com/v1/employees  // 雇员资源
           

• HTTP动词

  对于资源的操作(CURD)，由HTTP动词(谓词)表示。

  1. GET:从服务器取出资源(一项或多项)。
  2. POST: 在服务器新建一个资源。
  3. PUT: 在服务器更新资源(客户端提供改变后的完整资源)。
  4. PATCH: 在服务器更新资源(客户端提供改变的属性)。
  5. DELETE: 从服务器删除资源。
  例如：
  1. POST /zoos: 新建一个动物园
  2. GET /zoos/ID: 获取某个指定动物园的信息
  3. PUT /zoos/ID: 更新某个指定动物园的信息
  4. DELETE /zoos/ID: 删除某个动物园

• 过滤信息

  如果记录数量很多，服务器不可能都将它们返回给用户。

  API应该提供参数，过滤返回结果。

  例如：

  1. ?offset=10: 指定返回记录的开始位置
  2. ?page=2&per_page=100: 指定第几页，以及每页的记录数。
  3. ?sortby=name&order=asc: 指定返回结果排序，以及排序顺序。
  4. ?animal_type_id=1: 指定筛选条件。

• 状态码

  服务器向用户返回的状态码和提示信息，使用标准HTTP状态码。

  1. 200 OK 服务器成功返回用户请求的数据，该操作是幂等的。
  2. 201 CREATED 新建或修改数据成功。
  3. 204 NO CONTENT 删除数据成功。
  4. 400 BAD REQUEST 用户发出的请求有错误，该操作是幂等的。
  5. 401 Unauthorized 表示用户未认证，无法进行当前操作。
  6. 403 Frobidden 表示用户访问是被禁止的。
  7. 422 Unprocesable Entity 当创建一个对象时，发生一个验证码错误。
  8. 500 INTERNAL SERVER ERROR 服务器发生错误，用户将无法判断发出的请求是否成功。

• 错误处理

  如果状态码是4xx或5xx，就应该向用户返回出错信息。一般来说，返回的信息中将error作为键名，出错信息作为键值即可：

  {

  “error”: “参数错误”

  }

• 返回结果

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

  1. GET /collections: 返回对象的列表(数组)
  2. GET /collections/identity: 返回单个资源对象
  3. POST /collections: 返回新生成的资源对象
  4. PUT /collections/identity: 返回完整的资源对象
  5. PATCH /collections/identity: 返回被修改的属性
  6. DELETE /collections/identity: 返回一个空文档
• URL设计

/模块/资源/{标识}/集合1/…

例如：

/user/{uid}/friends -->好友列表
/user/{uid}/followers --> 关注者列表