00. review

接口规范

本接口规范参考 Github API 制定方式，遵循 RESTful 的接口格式。REST 全称是 Representational State Transfer，中文意思是表述性状态转移。本接口为纯数据接口。

资源

RESTFul 中的表述指的就是资源（Resource）的表述，资源的复数形式又称为集合（Collection）。本项目中的资源共有如下几种：

名称	资源名	集合名
大库	repository	repositories
图标	icon	icons
项目	project	projects
日志	log	logs
用户	user	-

注意：实体**车（cart）**不存在于存储层，因此不由本接口文档控制。

统一资源接口（URI）

使用标准的HTTP方法进行接口请求，符合其语义。常用的方法有：

方法	语义	安全性	幂等性
GET	获取资源	安全	幂等
POST	创建资源	不安全	非幂等
PUT	更新替换资源	不安全	非幂等
PATCH	部分更新资源	不安全	幂等
DELETE	删除资源	不安全	幂等

接口格式

本接口的接收和相应格式均为 json 格式。接口在请求成功时和失败时，统一将对应的数据与错误信息包入 data 和 errmsg 字段中，其外部再包裹一层对象，对象包含接口的公用信息（一般有成功与否、接口版本信息、接口错误码等，目前仅有标示接口成功与否的 ret 字段）。请求成功的样例如下所示（即 ret 参数为 true，数据字段为 data）：

{
    "ret": true,
    "data": [
        {
            "id": 1,
            "name": "hello"
        },
        {
            "id": 2,
            "name": "hi"
        }
    ]
}

如果包含分页信息，则数据接口会增添 page 字段：

{
    "ret": true,
    "data": [
        {
            "id": 1,
            "name": "hello"
        },
        {
            "id": 2,
            "name": "hi"
        }
    ],
    "page": {
        "currentPage": 1,
        "pageSize": 10,
        "totalCount": 100
    }
}

请求失败的样例如下所示（即 ret 参数为 false，数据字段为 errmsg）：

{
    "ret": false,
    "errmsg": "输入的用户名不合法！"
}

注意问题

1. 由于使用标准的 HTTP 方法对资源进行操作，因此 URI 中不应包含动词描述，如果需要表示行为需要用名词代替，同时在参数中表示行为转移的源与目标；
2. 鉴于 PUT PATCH DELETE 方法的不安全性，在应用中需要进行特殊处理，可以安装诸如 unirest 之类的 node 依赖；
3. 所谓幂等指的是：请求成功执行所得到的的结果不依赖于该方法被执行的次数，这里可以以 PUT、PATCH 方法为例，PUT 方法是实体无结构，直接将实体数据替换到服务器资源中；而 PATCH 方法提供的实体需要根据解析定义执行来修改服务器数据，可能导致累计修改的情况发生。有两篇文章深入讲解并举例说明了两者的区别：区分PATCH与PUT、POST方法 与 RESTful API Design Read the Docs