概述 - PingCodeRESTAPI

欢迎使用

欢迎使用 PingCode Representational State Transfer APIs （简称PingCode REST API）。 PingCode REST API 用于通过 HTTP 与 PingCode 服务端进行远程交互，例如创建、修改、查询、删除PingCode的资源。

接口调用流程

URI结构

PingCode REST API 通过URI路径提供对资源的访问，使用 {} 将URI路径的一部分标记为可使用参数替换的部分，URI 路径遵循以下规则：

https://rest_api_root/v1[/{area}]/{resource}

例如：

https://open.pingcode.com/v1/scm/products
https://open.pingcode.com/v1/scm/products/{product_id}/repositories
https://open.pingcode.com/v1/release/environments

rest_api_root表示根路径，在不同的环境中根路径有所不同：

公有云的REST API根路径：https://open.pingcode.com
私有部署的REST API根路径：https://xxxxxx/open

数据结构

PingCode REST API 使用 json 作为通讯格式，所有时间均使用 10 位数字组成的时间戳。 PingCode REST API 为每一种资源定义两种数据结构，全量结构和引用结构。全量结构包含资源的所有属性，引用结构只包含必要属性。当获取单个资源或分页获取资源列表时，PingCode REST API 将返回全量结构；当获取其他资源引用当前资源时，PingCode REST API 将返回引用结构。

全量结构

{
     "id": "5e05d8448f8461dada9ba29c",
     "url": "https://rest_api_root/v1/{resource}",
     "name": "资源名称",
     "desc": "资源简介",
     "created_at": 1578897962
}

引用结构

{
     "id": "5e05d8448f8461dada9ba29c",
     "url": "https://rest_api_root/v1/{resource}",
     "name": "资源名称"
}

使用方式

PingCode REST API支持 OPTIONS/GET/PUT/PATCH/POST/DELETE 等标准的HTTP请求。对于GET/DELETE请求，通过querystring传递参数；对于POST/PUT/PATCH请求，需要在headers中添加"content-type": "application/json"，然后通过body传递参数。 PingCode REST API使用HTTP状态码指示已执行操作的状态；使用response body传递数据。

单个资源

当创建、更新、获取、删除单个资源成功时，会返回当前操作的资源。

HTTP状态码：201
Body：
{
     "id": "5e05d8448f8461dada9ba29c",
     "url": "https://rest_api_root/v1/{resource}",
     "name": "资源名称",
     "desc": "资源简介",
     "created_at": 1578897962
}

分页数据

当请求多条数据时，默认每一页返回30条，最大返回100条。通过在querystring中设置page_size和page_index，指定每一页的数据量和第几页的数据（page_index为0时，表示第一页）。在返回的数据结构中，page_size表示当前每页的数据量，page_index表示当前在第几页，total表示资源总数量，values表示资源的数组。

HTTP状态码：200
Body：
{
     "page_size": 30,
     "page_index": 0,
     "total": 100,
     "values": [
         {
             "id": "5e05d8448f8461dada9ba29c",
             "url": "https://rest_api_root/v1/{resource}",
             "name": "资源名称",
             "desc": "资源简介",
             "created_at": 1578897962
         },
         ...
     ]
}

错误

当请求失败时，会返回错误码和错误信息。

HTTP状态码：500
Body：
{
     "code": "100000",
     "message": "Internal Server Error"
}

频率限制

PingCode REST API限制使用者的请求频率，目的是保障核心服务的可靠且响应迅速。频率限制不用于区分客户和服务级别。

具体策略

根据使用者的身份标识，PingCode REST API最多允许每位使用者每分钟请求200次，单位分钟内超出限制数量的HTTP请求将统一返回错误信息。

HTTP状态码：429
Headers：
{
     "x-pc-retry-after": 50
}
Body：
{
     "code": "100038",
     "message": "请求频率过高"
}

x-pc-retry-after指示使用者在重新请求之前必须等待的秒数。如果使用者在到期之前重新发出请求，则请求会再次失败并返回相同的HTTP状态码和response body。

合理请求

由于频率限制的存在，最小化请求将十分必要，一个显而易见的策略是缓存不会轻易变更的数据。另外使用PingCode Flow中的发送Webhook和发送HTTP请求来将PingCode中发生变更的数据发送给订阅者，也可以有效降低 PingCode REST API的请求数量，从而降低遇到频率限制的风险。

概述

欢迎使用#

接口调用流程#

URI结构#

数据结构#

全量结构#

引用结构#

使用方式#

单个资源#

分页数据#

错误#

频率限制#

具体策略#

合理请求#