概述 - 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 会对请求实施频率限制。公有云与私有部署环境采用不同策略。

公有云

公有云同时启用两层限流，任一达到上限即触发限流：

企业限流：按企业统计每分钟请求总数（RPM）

单接口突发限流：按企业 + HTTP Method + Route 统计每秒请求总数（RPS）

企业限流

按企业独立计数，每分钟重置一次。各版本配额如下：

企业版本	每分钟请求上限（RPM）	说明
免费版	200	固定配额，全企业共享
付费版	500 + 用户数 × 20	固定 500，每增加 1 名成员额外增加 20

单接口突发限流

按企业 + HTTP Method + Route 独立计数，每秒重置一次。默认配额如下：

HTTP 方法	请求上限（RPS）
GET / POST / PATCH / PUT / DELETE	30

响应头

无论是否触发限流，公有云响应均会携带以下限流状态头：

Header	说明
X-RateLimit-Team-Limit	企业每分钟请求配额上限
X-RateLimit-Team-Remaining	当前周期内企业剩余可用请求数
X-RateLimit-Team-Reset	企业配额重置的 Unix 时间戳（秒，UTC）
X-RateLimit-Burst-Limit	当前路由每秒请求配额上限
X-RateLimit-Burst-Remaining	当前周期内路由剩余可用请求数
X-RateLimit-Burst-Reset	路由配额重置的 Unix 时间戳（秒，UTC）

当返回 429 时，额外返回：

Header	说明
X-RateLimit-Retry-After	建议重试等待秒数
X-RateLimit-Reason	触发限流的原因。企业限流为 pingcode-team，单接口突发限流为 pingcode-burst

HTTP状态码：429
Headers：
{
     "X-RateLimit-Team-Limit": 200,
     "X-RateLimit-Team-Remaining": 0,
     "X-RateLimit-Team-Reset": 1785023460,
     "X-RateLimit-Burst-Limit": 30,
     "X-RateLimit-Burst-Remaining": 20,
     "X-RateLimit-Burst-Reset": 1785023412,
     "X-RateLimit-Retry-After": 50,
     "X-RateLimit-Reason": "pingcode-team"
}
Body：
{
     "code": "100038",
     "message": "请求频率过高"
}

私有部署

默认每人每分钟请求上限为 200，限流额度支持管理员配置。触发限流时，响应头仅返回 X-PC-Retry-After（建议重试等待秒数）。

HTTP状态码：429
Headers：
{
     "X-PC-Retry-After": 50
}
Body：
{
     "code": "100038",
     "message": "请求频率过高"
}

合理请求

由于存在频率限制，最小化请求十分必要，建议：

合理规划请求频率：公有云按企业版本配额评估并发，私有部署结合实例配置评估并发。

处理限流响应：收到 429 时，读取对应重试头设置延迟后再重试，避免立即重试导致持续限流。

监控剩余配额：通过 X-RateLimit-Team-Remaining、X-RateLimit-Burst-Remaining 提前预判额度并主动降速。

优先使用批量接口，减少请求次数。

缓存不会轻易变更的数据。

另外，使用 PingCode Flow 中的发送 Webhook 和发送 HTTP 请求，将变更数据推送给订阅者，也可以有效降低 REST API 请求量，从而降低触发频率限制的风险。

概述

欢迎使用#

接口调用流程#

URI结构#

数据结构#

全量结构#

引用结构#

使用方式#

单个资源#

分页数据#

错误#

频率限制#

公有云#

企业限流#

单接口突发限流#

响应头#

私有部署#

合理请求#