因工作需要,最近需要做webapi接口,领导强烈要求使用RESTful的软件架构风格,所以研究了一下RESTful,本文小结了RESTful的设计规范,也并不全面,主要是总结了下项目所需的规范。
1、URI规范说明
URI 表示资源,资源一般对应服务器端领域模型中的实体类。
URI规范
- 不用大写;
- 用中杠-不用下杠_;
- 参数列表要encode;
- 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的分类下