Restful十大设计规范

RESTfull设计规范

1.域名

1）子域名方式

https://api.example.com 尽量将API部署在专用域名（会存在跨域问题）

https://www.example.com

2）url方式

https://example.org

https://example.org/api/ API很简单

2.版本

将API的版本号放入URL中。

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

https://api.example.com/v2/

https://api.example.com/v3/

3.路径

路径又称“终点”，表示API的具体网址，每个网址代表一种资源

1） 资源作为网址，只能有名词，不能有动词，而且所用的名词往往与数据库的表名对应。

2）API中的名词应该使用复数。无论子资源或者所有资源。

/getProducts　　　　不符合REST风格

/Orders 　　　　　　 符合REST风格

获取单个产品：http://127.0.0.1:8080/AppName/products/1

获取所有产品：http://127.0.0.1:8080/AppName/products

4.方式

GET ：从服务器取出资源（一项或多项）

POST ：在服务器新建一个资源

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

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

DELETE ：从服务器删除资源

5.过滤

通过在url上传参的形式传递搜索条件

https://api.example.com/v1/zoos?limit=10：指定返回记录的数量

https://api.example.com/v1/zoos?offset=10：指定返回记录的开始位置

https://api.example.com/v1/zoos?page=2&per_page=100：指定第几页，以及每页的记录数

https://api.example.com/v1/zoos?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序

https://api.example.com/v1/zoos?animal_type_id=1：指定筛选条件

6.状态码

状态码

7.异常处理

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

{ error: “Invalid API key” }

8.返回结果

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

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

GET /collection/resource：返回单个资源对象

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

PUT /collection/resource：返回完整的资源对象

PATCH /collection/resource：返回完整的资源对象

DELETE /collection/resource：返回一个空文档

9.超媒体（Hypermedia API）

RESTful API最好做到Hypermedia（即返回结果中提供链接，连向其他API方法），使得用户不查文档，也知道下一步应该做什么。

比如，Github的API就是这种设计，访问api.github.com会得到一个所有可用API的网址列表。

10、数据传输格式

restful是一种软件设计风格，并不是标准，他只是提供了一组设计原则和约束条件
1.restful提倡面向资源编程，url接口尽量要使用名词，不要使用动词
2.在url中可以体现版本号
3.可以根据http不同的method，进行不同的资源操作
4.有返回值，而且格式为统一的json格式