转载自：https://jsbintask.cn/2019/03/20/api/restful-api-best-practices/
rest = representational state transfer三个单词的缩写
1、rest设计规则：
1、前后端分离的思想
2、从客户端到服务器的每个请求都必须包含理解请求所需的所有信息，并且不能利用服务器上任何存储的上下文。
3、REST接口约束定义：
资源识别; 请求动作; 响应信息; 它表示通过uri标出你要操作的资源，通过请求动作（http method）标识要执行的操作，通过返回的状态码来表示这次请求的执行结果。
2、uri规范：
1、使用名词，如http://api.example.com/class-management/students
2、http method对应不同的请求动作（数据库或者业务逻辑）
GET：查询操作：
HTTP GET /devices?startIndex=0&size=20
POST：新增操作：
HTTP POST /device
PUT 更新操作（代表更新一个实体的所有属性）
HTTP PUT /devices/{id}
PATCH 部分更新（代表更新一个尸体的部分属性）由于有的浏览器兼容性问题，一般推荐使用put
HTTP PATCH /devices/{id}
DELETE 删除操作
HTTP DELETE /devices/{id}
3、用连字符（ - ）而不是（_）来提高URI的可读性
http://api.example.com/inventory-management/managed-entities/{id}/install-script-location //更易读
http://api.example.com/inventory_management/managed_entities/{id}/install_script_location //更容易出错
4、URI中使用小写字母
http://api.example.org/my-folder/my-doc
5、不要使用文件扩展名 文件扩展名看起来很糟糕，不会增加任何优势。删除它们也会减少URI的长度。没理由保留它们。
http://api.example.com/device-management/managed-devices.xml / 不要使用它 /
http://api.example.com/device-management/managed-devices / 这是正确的URI /
6、使用查询组件过滤URI集合
很多时候，我们会遇到需要根据某些特定资源属性对需要排序，过滤或限制的资源集合的要求。为此，请不要创建新的API - 而是在资源集合API中启用排序，过滤和分页功能，并将输入参数作为查询参数传递。例如
http://api.example.com/device-management/managed-devices
http://api.example.com/device-management/managed-devices?region=USA
http://api.example.com/device-management/managed-devices?region=USA&brand=XYZ
http://api.example.com/device-management/managed-devices?region=USA&brand=XYZ&sort=installation-date
7、不要在末尾使用/
作为URI路径中的最后一个字符，正斜杠（/）不会添加语义值，并可能导致混淆。最好完全放弃它们。
8、api版本定义
当我们需要对现有的api接口升级的时候，因为该api接口已经投入使用，所以新添加的业务可能无法保证兼容原来的逻辑，这个时候就需要新的接口，而这个接口一般表示对原来的接口的升级（不同版本），那版本怎么定义呢？
URI版本控制（推荐）
使用自定义请求标头进行版本控制
Accept-version：v1
Accept-version：v2
使用Accept header 进行版本控制
Accept:application / vnd.example.v1 + json
Accept:application / vnd.example + json; version = 1.0
总结：
1、HTTP动词
常用的HTTP动词有下面五个
GET（SELECT）：从服务器取出资源（一项或多项）。
POST（CREATE）：在服务器新建一个资源。
PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。
PATCH（UPDATE）：在服务器更新资源（客户端提供改变的属性）。
DELETE（DELETE）：从服务器删除资源
2、RESTful架构
服务器上每一种资源，比如一个文件，一张图片，一部电影，都有对应的url地址，如果我们的客户端需要对服务器上的这个资源进行操作，就需要通过http协议执行相应的动作来操作它，比如进行获取，更新，删除。
简单来说就是url地址中只包含名词表示资源，使用http动词表示动作进行操作资源
举个例子：左边是错误的设计，而右边是正确的
GET/blog/getArticles-->GET/blog/Articles 获取所有文章
GET/blog/addArticles-->POST/blog/Articles 添加一篇文章
GET/blog/editArticles-->PUT/blog/Articles 修改一篇文章
GET/rest/api/deleteArticles?id=1-->DELETE/blog/Articles/1 删除一篇文章
此处转载于链接：https://www.jianshu.com/p/6baf8554b3f4
3、怎么用RESTful
一、每个资源使用2个URL，网址中只能有名词
二、对于资源的操作类型由HTTP动词来表示
三、统一的返回结果
四、返回正确的状态码
五、允许通过HTTP内容协商，建议格式预定义为JSON
六、对可选发杂的参数，使用查询字符串（？）
七、返回有用的错误信息(message)
八、非资源请求用动词，这看起似乎和1中的说法有矛盾，但这里指的是非资源，而不是资源
链接：https://www.jianshu.com/p/0e7e379afc6f
网友评论