API 文档编写规范（URL篇）

风格

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