API 文档编写规范（URL篇）
2020-03-08 本文已影响0人
简栋梁
风格
POST
协议 + 域名/IP + 端口号 + /api + /项目名 + /一级资源 + /n级资源 + 动作
如：http://127.0.0.1:6666/api/user/detail/get
RESTful
协议 + 域名/IP + 端口号 + /api + /项目名 + /一级资源 + /n级资源
如：GET http://127.0.0.1:6666/api/user/detail
URL参数
统一使用 & 连接键值对的方式
如：http://127.0.0.1:6666/api/user/get?name_user=Tony&sex_user=1
| 方法 | 描述 |
|---|---|
| HEAD | 可以对任何资源发出请求，以获取HTTP头信息 |
| GET | 查找资源 |
| POST | 创建资源 |
| PATCH | 替换资源的部分信息 |
| PUT | 替换资源的全部信息，要求请求信息是完整的。若某字段不传递，则赋予默认值 |
| DELETE | 删除资源 |
注意点
版本号不应写在URL中
不同版本，可以理解成同一种资源的不同表现形式，所以应该采用同一个URL。版本号可以在HTTP请求头信息的 Accept 字段中进行区分
Accept: vnd.example-com.foo+json; version=1.0
Accept: vnd.example-com.foo+json; version=1.1
Accept: vnd.example-com.foo+json; version=2.0
RESTful URL 只出现名词
如果某些动作是HTTP动词表示不了的，你就应该把动作做成一种资源。比如网上汇款，从账户1向账户2汇款500元，错误的URI是：
POST /accounts/1/transfer/500/to/2
正确的写法是把动词transfer改成名词transaction，资源不能是动词，但是可以是一种服务：
POST /transaction
