起步

    CODING OpenAPI 采用 风格设计。

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

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

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

    基础地址（Base URL）为：

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

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

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

    可以设置至 http 请求的 Header 中

    1. ~ curl -H "Authorization: token 90ed7a169febb12d17e14aa5531827476f6b3a4e" https://test.coding.net/api/current_user
    2. {
    3.     "code": 0,
    4.     "data": {
    5.         "global_key": "testuser",
    6.         "name": "testuser",
    7.         ...
    8.     }
    9. }

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

    1. ~ curl -u testuser https://test.coding.net/api/current_user
    2. Enter host password for user 'testuser':
    3. {
    4.     "code": 0,
    5.     "data": {
    6.         "global_key": "testuser",
    7.         ...
    8.     }
    9. }

    或者

    1. ~ curl -u "testuser:90ed7a169febb12d17e14aa5531827476f6b3a4e" https://test.coding.net/api/current_user
    2. {
    3.     "code": 0,
    4.     "data": {
    5.         "global_key": "testuser",
    7.         ...
    8.     }
    9. }

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

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

    参数传入方式

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

    1. POST "https://coding.net/api/social/follow" -d "users=chenjuntong"
    2. Content-Type: application/json
    3. {
    4.   "data": {
    5.     "project_id": 1,
    6.     "parent_id": 0,
    7.     "name": "注册"
    8.   }
    9. }

    分页参数

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

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

    响应

    成功响应格式

    仅仅返回成功标示
    1. {
    2.   "code": 0
    3. }
    返回实体详情结构

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

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

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

    1. {
    2.   "code": 0,
    3.     {
    6.   ]
    7. }
    返回实体详情列表【分页】

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

    1. {
    2.   "code": 0,
    3.   "data": {
    4.     "list": [
    5.       {
    6.         "code": "code",
    7.         "value": "value",
    8.         "description": "des",
    9.         "status": 0,
    10.         "created_at": 1544605663000,
    11.         "updated_at": 1544605663000,
    12.         "id": 11
    13.       }
    14.     ],
    15.     "page": 1,
    16.     "pageSize": 10,
    17.     "totalPage": 1,
    18.     "totalRow": 10
    19.   }
    20. }

    错误返回格式

    仅仅返回失败标示
    1. {
    2.   "code": 1
    3. }
    带有业务类型的错误返回格式

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

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

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