起步

CODING OpenAPI 将部分网站服务封装成一系列 API（Application Programming Interface，应用编程接口）开放出来，供第三方开发者使用。

CODING OpenAPI 采用 RESTFul 风格设计。

所有的 OpenAPI 请求地址都是 可预期的 以及 面向资源 的，并且使用规范的 HTTP 响应代码 来标识请求结果的正确与错误信息。

所有的 OpenAPI 请求都会以规范友好的 JSON 对象格式返回（包括错误信息），并且使用「个人访问令牌」Personal Access Token 作为鉴权方法。

所有请求和响应的编码均为 UTF-8。

调用说明

基础地址（Base URL）为：

https://coding.net

鉴权方法

「个人访问令牌」Personal Access Token 类似某些系统中的应用专用密码。生成后可根据设置的权限访问特定的 OpenAPI。

关于个人访问令牌请访问 这里。

生成自己的个人访问令牌请到 这里。

「个人访问令牌」形如 90ed7a169febb12d17e14aa5531827476f6b3a4e。

可以设置至 http 请求的 Header 中

~ curl -H "Authorization: token 90ed7a169febb12d17e14aa5531827476f6b3a4e" https://test.coding.net/api/current_user
{
    "code": 0,
    "data": {
        "global_key": "testuser",
        "name": "testuser",
        ...
    }
}

也可以在 http 请求中使用 -u 参数，加入用户。

~ curl -u testuser https://test.coding.net/api/current_user
Enter host password for user 'testuser':
{
    "code": 0,
    "data": {
        "global_key": "testuser",
        "name": "testuser",
        ...
    }
}

或者

~ curl -u "testuser:90ed7a169febb12d17e14aa5531827476f6b3a4e" https://test.coding.net/api/current_user
{
    "code": 0,
    "data": {
        "global_key": "testuser",
        "name": "testuser",
        ...
    }
}

请求

所有的请求方式（Method）均与动词相关：

• GET：获取资源
• POST：创建资源
• DELETE：删除资源
• OPTIONS：获取客户端能对资源做什么操作的信息

参数传入方式

如无特别说明，GET 请求参数需要放到 Url Query String 中：

GET "https://coding.net/api/account/current_user"

POST/PUT/PATCH 请求参数建议使用 JSON 格式将参数放到请求体中：

POST "https://coding.net/api/social/follow" -d "users=chenjuntong"
Content-Type: application/json
{
  "data": {
    "project_id": 1,
    "parent_id": 0,
    "name": "注册"
  }
}

分页参数

支持分页的列表接口，支持传入当前页（page） 和 每页显示条数（pageSize） 来自定义返回。例如：

GET "https://coding.net/api/user/projects?type=all&sort=hot&page=1&pageSize=10"

响应

成功响应格式

仅仅返回成功标示

{
  "code": 0
}

返回实体详情结构

成功响应中包含 code 资源，data 元数据，如：

{
  "code": 0,
  "data": {
    "code": "code",
    "value": "value",
    "description": "des",
    "status": 0,
    "created_at": 1544542013629,
    "updated_at": 1544542013629,
    "id": 12
  }
}

返回实体详情列表【不分页】

成功响应中包含 code 资源，data 元数据，如：

{
  "code": 0,
  "data": [
    {
    }
  ]
}

返回实体详情列表【分页】

成功响应中包含 code 资源，data 元数据，如：

{
  "code": 0,
  "data": {
    "list": [
      {
        "code": "code",
        "value": "value",
        "description": "des",
        "status": 0,
        "created_at": 1544605663000,
        "updated_at": 1544605663000,
        "id": 11
      }
    ],
    "page": 1,
    "pageSize": 10,
    "totalPage": 1,
    "totalRow": 10
  }
}

错误返回格式

仅仅返回失败标示

{
  "code": 1
}

带有业务类型的错误返回格式

错误相应中包含 code 业务错误代码，msg 错误描述，如：

{
  "code": 500001,
  "msg": {
    "user_not_login":"用户未登录"
   }
}

全局错误码

API 使用 HTTP 状态码 (status code) 来表明一个 API 的系统状态。

• HTTP 200 表明 API 请求成功或业务失败。
• HTTP 404 表明 API 不存在。
• HTTP 500 表明 API 请求时，服务器应用发生了错误。

字段类型

在文档中，我们将使用许多不同类型的数据。您可以在下方的说明列表找到它们的解释及含义。