Contents
一、标题
此文档为文档说明
API 版本
| 版本 | 内容 |
|---|---|
| 1.0 | 一个版本内容 |
调用说明
API 遵循 REST 标准进行设计。
我们的 API 是 可预期的 以及 面向资源 的，接受 form-encoded 或JSON请求正文，返回 JSON-encoded 响应， 使用标准的 HTTP 响应代码和参数。
所有请求和响应的编码均为 UTF-8。
基础地址：
https://localhost:8080/api/v1
请求
所有的请求方式（Method）均与动词相关：
GET：获取资源POST：创建资源PUT：更新资源PATCH：更新资源的一个属性DELETE：删除资源OPTIONS：获取客户端能对资源做什么操作的信息
参数传入方式
如无特别说明，GET 请求参数需要放到 Url Query String 中：
GET https://localhost:8080/api/v1/pet/findByTags?tags=abc
POST/PUT/PATCH 请求参数建议使用 JSON 格式将参数放到请求体中，例如：
PUT https://localhost:8080/api/v1/pet
Content-Type: application/json
{
"id": 1,
"category": {
"id": 1,
"name": "小型犬"
},
"name": "博美",
"photoUrls": "http://photocdn.sohu.com/20150811/mp26678520_1439257270139_10.jpeg",
"tags": [
{
"id": 1,
"name": "可爱"
}
],
"status": "available"
}
但是，对于比较少的参数（少于3个），通常会使用表单形式发送，具体使用什么形式取决于API定义。
响应
成功响应中包含实体资源内容，如：
[
{
"a": "xxx",
"b": "xxx"
},
{
"c": "xxx",
"d": "xxx"
}
]
错误
API 使用标准 HTTP 响应码（Status Code）来表示 API 请求。
通常，状态码：
2xx代表成功响应4xx代表失败响应，并给出失败原因5xx代表服务端内部错误
状态码说明
| 状态码 | 描述 |
|---|---|
| 200 | 更新/获取资源成功 |
| 201 | 创建资源成功 |
| 204 | 删除资源成功 |
| 400 | 业务错误，具体参见下放业务错误代码 |
| 401 | 认证失败，请返回 查参数是否有误 |
| 403 | 无权限调用接口，如：未开通 API 功能 |
| 404 | 资源不存在 |
| 405 | 接口请求方式 Method 有误 |
| 422 | 请求参数校验失败 |
| 429 | 触达限流限制 |
| 500 | 服务器应用发生了错误 |
| 502 | 服务器无法连接 |
| 503 | 服务器暂不可用 |
| 504 | 服务器连接超时 |
业务错误说明
通过 JSON 形式返回的响应数据，其中包括业务错误码 code 和错误原因 message，例如：
{
"code": -1,
"message": "项目不存在",
"data":{}
}
业务错误码 code 说明如下：
| 错误码 | 描述 |
|---|---|
| -1 | 小于0的错误码均为业务错误 |
| 0 | 未登录 |
| 1 | 响应成功 |
二、API列表
1.测试接口
概述：xxxx
请求地址：/api/aaa
请求方式：POST application/x-www-form-urlencoded
| 参数 | 类型 | 是否必传 | 参数含义 |
|---|---|---|---|
| username | String | 是 | 用户名 |
| password | String | 是 | 密码 |
| type | Integer | 否 | 类型，1为管理员2为普通会员，默认2 |
返回示例：
{
"code": 1,
"message": "创建成功",
"data": {
"id": 1002,
"hdfs": {
"filenum": 1024,
"capaticy": 500
}
}
}
data内字段含义：
| 参数 | 类型 | |
|---|---|---|
| id | Integer | 创建好的uid |
| hdfs | Object | hdfs信息 |
| > | ||
| filenum | int | 文件数目 |
| capaticy | int | 容量，单位G |
三、CURL使用说明
CURL是Linux下的一个命令行程序，用于发送HTTP等请求，本小节内容在于帮助文档阅读者快速测试API可用性。
1.发起GET请求
curl -X GET \
http://127.0.0.1:8080/api/v1/login?user=admin&passwd=12345678
2.发起POST请求
发送表单数据
curl -X POST \
-d "user=admin&passwd=12345678" \
http://127.0.0.1:8080/api/v1/login
发送JSON数据
curl -X POST \
-H "X-LC-Id: {{appid}}" \
-H "Content-Type: application/json" \
-d '{
"status" : "open",
"content" : "反馈的文字内容",
"contact" : "联系方式、QQ 或者邮箱手机等"
}' \
http://127.0.0.1:8080/api/v1/feedback
如果JSON比较复杂，可以将内容保存至文本，即可发送本地的JSON
curl -X POST \
-H "X-LC-Id: {{appid}}" \
-H "Content-Type: application/json" \
-d @/develop/soft/test.json \
http://127.0.0.1:8080/api/v1/feedback
3.HTTP基本认证（HTTP Basic Authentication）
curl -i --user username:password \
http://127.0.0.1:8080/api/v1/login
四、数据字典
1.权限（POWER）
| 字段 | 注释 |
|---|---|
| AAA | BBB |