Restful接口定义规则

一，HTTP方法及含义

方法名	含义
GET	获取资源
POST	创建资源
PUT	更新资源
DELETE	删除资源。RPC标准文档中规定该方法的请求体在语义上没有意义

二，URL定义规则

• 前置规则：所有资源都是用“复数”，且全小写(如果单词拼接,使用中划线‘-’)
• 整体思想：
  1）条件少且固定，而且不能为空，则可直接附加到URL路径中
  2）条件过多或不固定，则在路径中体现被操作的资源，取出大范围的集合后再进行条件筛选(条件作为查询参数或放在消息体中)

路径举例

GET /students/{id}   #ID不能为空的情况
GET /students?sortby=name&order=asc&offset=10&limit=5  #取出所有数据并分页
GET /classes/{calssId}/students  #取出指定班级下的所有学生(可以添加其他条件)
GET /classes/students #参数比较复杂，如：具备某些条件班级下的符合某些条件的学生。查询参数在body中

对于其它的增、删、改也都遵循同样的规则，如：

PUT /students/{id}  #更新单个资源(数据在body中)
POST /students     #新建资源(数据在body中)

三，是否带上版本

例如：

/api/customers/1234
还是
/api/v2.2/customers/1234

对于是否加版本号的问题，大致有两种论述

1，支持者

保持接口的向后兼容是一件十分困难或者说费精力的事情，而在URI中加入版本信息则避免了向后兼容，另外通过过期提示，重定向，文档等手段也能降低用户迁移到新的接口上的成本。

2，反对者

1） 不同API版本支持的资源类型是不一样的，当用户从一个版本切换到另外一个版本时原有的代码很有可能不能正常工作，这无疑加大了用户迁移的成本。

2） Restful服务中的URI对应着相应的资源，用户在请求某个URL时他们期望得到的是某个资源，而版本和资源的概念没有任何关系，因此在URI中加入版本会让用户混淆。（另外版本也不应用来指定资源的表现形式，例如json,xml）

3） 版本的加入会让整个Restful服务变得混乱，除非重写整个服务，否则你就会经常碰到这样的情况：一些低版本的资源指向了一些高版本的资源，如果不修改前者，那么很可能新的客户端代码会出错，如果修改前者，很可能旧的客户端代码会出错。）

版本号添加原则
1，如果接口是开放对外服务的，这样的接口加上版本。
2，如果接口是内部小范围使用且确定可控制，接口更新别人也会跟上，则可考虑不加。
但，总的来说还是建议加上版本号。对于新版本的发布一般是在接口输入输出参数变化时才会有。

四，请求响应结果

建议定义统一的响应结构，如：

public class MResult<T>{
  private Integer code ; //接口执行响应码
  private String msg ;  //响应码对于的消息
  private T data ;  //响应结果[真正的数据]
}

常用的响应码

响应码	含义
200	OK 接口调用正常返回
201	CREATED 资源已被成功创建
204	No Content 资源删除成功
401	Unauthorized 未认证
403	Forbidden 不允许的，服务端正常解析和请求，但调用被回绝(例如参数验证不对)
404	Not Found 操作的资源不存在
500	Internal Server Error 接口执行异常

https://docs.microsoft.com/en-us/azure/architecture/best-practices/api-design