协议
所有API前后端通信都使用HTTPS协议。
API 根地址
API的根地址应该保持简单,如:
- api.engineer.com/*
- www.engineer.com/api/*
如果应用很庞大或者预计后期会变的很庞大,应该将api放到子域下(api.engineer.com)。这样可以保持规模化上的灵活性。
版本
所有的API必须前后兼容。必须在引入新版本API的同时确保旧版本API仍然可用。所以要为API提供版本支持。如如下两种方式:
- 在URL中嵌入版本号
api.engineer.com/v1/*
这种做法版本号比较直观,还有一种嵌入版本号是放在HTTP Header头中
- 通过媒体类型来指定版本信息
Accept: application/vnd.engineer.com.v1+json
其中 vnd
表示 Standards Tree
标准树类型,有三个不同的树: x
,prs
和 vnd
。你使用的标准树需要取决于你开发的项目
- 未注册的树(
x
)主要表示本地和私有环境 - 私有树(
prs
)主要表示没有商业发布的项目 - 供应商树(
vnd
)主要表示公开发布的项目
端点
端点就是指定特定资源的URL。端点设计必须遵守以下原则:
- URL的命名必须全部小写
- URL中资源的全名必须是名词,并且必须是复数形式
- 必须优先使用Restful类型的URL
- URL必须是易读的
- URL一定不可暴露服务器架构
至于 URL 是否必须使用连字符(-
) 或下划线(_
),不做硬性规定,但要根据团队情况统一一种风格。
HTTP动词
对于资源的具体操作类型,由 HTTP 动词表示。常用的 HTTP 动词有下面五个
- GET:从服务器取出资源(一项或多项)。
- POST:在服务器新建一个资源。
- PUT:在服务器更新资源(客户端提供改变后的完整资源)。
- PATCH:在服务器更新资源(客户端提供改变的属性)。
- DELETE:从服务器删除资源。
注意:
1 删除资源 必须 用 DELETE 方法
2 创建新的资源 必须 使用 POST 方法
3 更新资源 应该 使用 PUT 方法
4 获取资源信息 必须 使用 GET 方法
响应
所有的 API 响应,必须遵守HTTP设计规范,必须选择合适的 HTTP 状态码。一定不可所有接口都返回状态码为200的HTTP响应。
以上内容摘录自:https://github.com/godruoyi/restful-api-specification