RestfulAPI定义和设计

Soap WebService和RESTful的区别？

效率和易用性：

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

RESTful

Restful由于其面向资源接口设计以及操作抽象简化了开发者的不良设计，同时也最大限度的利用了Http最初的应用协议设计理念。

安全性：

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

SOAP的成熟型可以给需要提供给多开发语言的，对于安全性要求较高的接口设计来带福利。所以我觉得纯粹说什么设计模式将会占据主导地位没有什么意义，关键还是要看应用场景。

 

如何设计RESTfulAPI？

1、资源路径（URL）

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

举例：有一个API提供动物园信息

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

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

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

2、HTTP动词

对于资源的操作（CRUD）,由HTTP动词（谓词）表示。

GET  ：从服务器获取资源

POST：在服务器新建资源

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

PATCH：在服务器更新资源（客户端提供改变的属性）

DELETE：从服务器删除资源

举例：

POST/zoos：新建一个动物园

GET/zoos/ID：获取某个指定的动物园

PUT/zoos/ID：更新某个指定的动物园

DELETE/zoos/ID：删除某个动物园

3、过滤信息

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

举例：

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

?anima_type_id=1：制定筛选条件

4、状态码

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

举例：

200 成功

204 删除成功

403 无法访问

5、错误处理

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

举例：

｛

         “error”:”参数错误”

｝

6、返回结果

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

GET/collections：返回资源对象的列表（数组）

GET/collections/identity：返回单个资源对象

POST/collections：返回新生成的资源对象

PUT/collections/identity：返回完整的资源对象

PATCH/collections/identity：返回被修改的属性

DELETE/collections/identity：返回一个空文档