RESTful接口API设计规范

因工作需要，最近需要做webapi接口，领导强烈要求使用RESTful的软件架构风格，所以研究了一下RESTful，本文小结了RESTful的设计规范，也并不全面，主要是总结了下项目所需的规范。

1、URI规范说明

URI 表示资源，资源一般对应服务器端领域模型中的实体类。

URI规范

1. 不用大写；
2. 用中杠-不用下杠_；
3. 参数列表要encode；
4. URI中的名词表示资源集合，使用复数形式。

高级别的模式

http(s)://server.com/app-name/{version}/{domain}/{rest-convention}

这里，{version}代表api的版本信息。{domain}是一个你可以用来定义任何技术的区域(例如：安全-允许指定的用户可以访问这个区域。)或者业务上的原因。(例如：同样的功能在同一个前缀之下。)

资源集合 vs 单个资源

URI表示资源的两种方式：资源集合、单个资源。

资源集合：

/categories    //所有分类
/categories/1/products    //id为1的分类下的所有商品

单个资源：

/categories/1    //id为1的分类
/categories/1;2;3    //id为1,2,3的分类

避免层级过深的URI

/在url中表达层级，用于按实体关联关系进行对象导航，一般根据id导航。

过深的导航容易导致url膨胀，不易维护，如 GET /categories/1/areas/3/products/4，尽量使用查询参数代替路径中的实体导航，如GET /products?category=1&area=3；

2、Request

HTTP方法

通过标准HTTP方法对资源CRUD

GET(查询):

GET /categories    //所有分类
GET /categories/1    //id为1的分类
GET /categories/1/products    //id为1的分类下的所有商品

POST(创建单个资源。POST一般向“资源集合”型uri发起):

POST /products    //新增商品
POST /categories/1/properties    //id为1的分类下创建属性

PUT(更新单个资源（全量），客户端提供完整的更新后的资源。与之对应的是 PATCH，PATCH 负责部分更新，客户端提供要更新的那些字段。PUT/PATCH一般向“单个资源”型uri发起):

PUT /products/1    //修改id为1的商品
PUT /categories/1    //修改id为1的分类

DELETE(删除):

DELETE /products/1    //删除id为1的商品
DELETE /categories/1/products/1;2;3    //删除id为1的分类下id为1,2,3的商品
DELETE /categories/1/properties    //删除id为1的分类下所有属性

安全性和幂等性

1. 安全性：不会改变资源状态，可以理解为只读的；
2. 幂等性：执行1次和执行N次，对资源状态改变的效果是等价的。