RESTful API 设计精要-CSDN博客

文章目录

一、restful简介
- 设计概念和准则：
二架构区别
三、设计要素

一、restful简介

RESTful本质是一种软件架构风格，核心是面向资源。解决的问题：降低开发的复杂性、提高系统的可伸缩性。

设计概念和准则：

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

资源：所谓资源，就是网络上的一个实体，或者说是网络上的一个具体信息。

二架构区别

SOAP WebService

WebService是一种跨编程语言和跨操作系统平台的远程调用技术
WebService 通过HTTP协议发送请求和接收结果时采用XML格式封装，并增加了一些特定的HTTP消息头，这些特定的HTTP消息头和 XML内容格式就是SOAP

区别

效率和易用性

Soap由于各种需求不断扩充其本身协议的内容，导致在SOAP处理方面的性能有所下降，同时在易用性方面以及学习成本上也有所增加。
RESTful由于其面向资源接口设计以及操作抽象简化了开发者的不良设计，同时也最大限度的利用了Http最初的应用协议设计理念。

安全性

RESTful对于资源型服务接口来说很合适，同时特别适合对于效率要求高，但是对于安全要求不高的场景
SOAP的成熟性可以给需要提供给多开发语言的，对于安全性要求较高的接口设计带来便利。所有我觉得纯粹说什么设计模式将会占据主导地位没有什么意义，关键还是看应用场景。

三、设计要素

资源路径

      在RESTful架构中，每个网址代表一种资源，所以网址中不能有动词，只能有名词。一般来说API中的名词应该使用复数。
      eg：https://api.example.com/v1/zoos ///动物园资源
              https://api.example.com/v1/animals///动物资源
             https://api.example.com/v1/employees //雇员资源

HTTP动词

    对于资源的操作（CURD），由HTTP动词（谓词）表示

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

eg:POST /zoos:新建一个动物园
GET /zoos/ID:获取某个指定动物园的信息
PUT /zoos/ID：更新某个指定动物园的信息
DELETE /zoos/ID:删除某个动物园

过滤信息

如果记录数量很多，服务器不可能都将它们返回给用户。API应该提供参数，过滤返回结果。
eg:
?offset=10:指定返回记录的开始位置
？page=2&per_page=100:指定第几页，以及每页的记录数
？sortby=name&order=ase:指定返回结果排序，以及排序顺序
？animal_type_id=1:指定筛选条件

状态码

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

  200 OK      400       401 没有认证    403  访问被禁止  422验证错误  5.00服务器内部错误

错误处理

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

     {
        “error”:“参数错误”
     }

返回结果

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

GET /collections:返回资源对象的列表
GET /collections/identity：返回单个资源对象
POST /collections :返回新建的资源对象
PUT /collections/identity：返回完整的资源对象
PATCH /collections/identity:返回新建的资源对象