Rest

概念

• Web API 两种风格：面向过程（RPC）、面向 REST（REST）
• RPC：“控制器/操作方法“ 的形式把服务器端的代码当成方法去调用。把HTTP当成传输数据的通道，不关心HTTP谓词。
• REST：按照HTTP的语义来使用HTTP协议，一种基于资源的软件架构风格
• Restful 优点：
  • 降低开发的复杂性
  • 提供系统的可伸缩性
  • 只需设计一套相同的后端处理接口，就可以为不同类型的终端提供服务
  • 通过URL对资源定位，语义更清晰；
  • 通过HTTP谓词表示不同的操作，接口自描述；
  • 通过HTTP状态码反映服务器端的处理结果，统一错误处理机制。
• 设计原则：
  • 网络上的所有事物都可以被抽象为资源
  • 每一个资源都有唯一的资源标识，对资源的操作不会改变这些标识
  • 所有的操作都是无状态的（每次操作都是独立的，互不关联）
• 对资源的操作由 HTTP 谓词表示
• 针对不同操作，服务器向用户返回的结果应该符合规范
• 服务器向用户返回的状态码和提示信息，使用标准 HTTP 状态码

HTTP 谓词

• GET（获取）、POST（新增）、PUT（整体更新）、DELETE（删除）、PATCH（局部更新）
• OPTIONS 请求查询服务器的性能，或者查询与资源相关的选项和需求；

返回结果规范

• GET/collections：返回资源对象的列表（数组）
• GET/collections/identity：返回单个资源对象, 如果资源不存在，返回404状态码；
• POST/collections：返回新生成的资源对象（返回新创建的资源的全部属性）
• PUT/collections/identity：返回完整的资源对象（返回被更新资源的完整属性）
• PATCH/collections/identity：返回被修改的属性
• DELETE/collections/identity：返回一个空文档 删除了资源，要返回204状态码。

HTTP 状态码

• 200 OK 服务器成功返回用户请求的资源，该操作是幂等的。
• 204 NO CONTENT 删除数据成功（无响应体）。
• 400 Bad Request 用户发出的请求有错误，该操作是幂等的。
• 401 Unauthorized 表示用户没有认证，无法进行当前操作（用户未提供认证选项或参数）。
• 403 Forbidden 表示用户访问是被禁止的。（用户提供了认证参数，但可能认证参数错误，或无权限）。
• 422 Unprocesable Entity 当创建一个对象时，发生一个验证错误（验证信息不全）。
• 500 Internal Server Error 服务器发生错误，用户将无法判断发出的请求是否成功。
• 503 Server Unavailable //服务器当前不能处理客户端的请求（服务器性能达到瓶颈时，拒绝后续服务）

参数传递

• Url：用于资源定位
• QueryString：用于 URL 之外的额外数据
• 请求报文体：供 PUT、POST 提供数据

Rest实现参考

• 使用 RPC 风格：Users/AddNew、Users/GetAll、Users/DeleteById
• 对于可以缓存的操作，使用GET请求；对于幂等的更新操作，使用PUT请求；对于幂等的删除操作，使用DELETE请求；对于其他操作，统一使用POST请求。
• 保存、更新类的请求使用POST、PUT请求，把全部参数都放到请求报文体中；对于GET和DELETE请求，把参数放到QueryString中。推荐尽量使用URL做资源定位。
• 对于业务错误，服务器端返回合适的4XX状态码；同时，在报文体中通过code参数提供业务错误码以及错误消息。
• 如果请求的处理执行成功，服务器端返回值为200的Http状态码，如果有需要返回给客户端的数据，则服务器端把这些数据放到响应报文体中。