一、标题

此文档为文档说明

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