# 使用前必读
# 如何调用
每个 API 均符合标准 RESTFUL 规范，每个请求的路径均包含/api/v3。比如：
GET https://git.tencent.com/api/v3/projects?private_token=ddwnTYP0bBSWaDPD7_NY
在接口文档说明中，会注明应当使用那种 HTTP 方法，可以是GET,POST,PUT,DELETE
- 如果接口用于获取数据，则成功时返回
200 OK，返回值为JSON格式 - 如果接口用于插入或创建数据，成功时返回
201 Created，并会把新创建的项目用JSON格式返回 - 如果接口用于修改数据，则成功时返回
200 OK，同时修改了的数据会以JSON格式返回 - 如果接口用于删除数据，则成功时返回
200 OK
# 返回值
| 返回值 | 涵义 |
|---|---|
200 OK | 操作成功 |
201 Created | 创建成功 |
400 Bad Request | 参数错误，或是参数格式错误 |
401 Unauthorized | 认证失败 |
403 Forbidden | 帐号并没有该操作的权限或者项目设置不允许该操作 |
404 Not Found | 资源不存在，也可能是帐号没有该项目的权限（为防止黑客撞库获取库列表） |
405 Method Not Allowed | 没有该接口 |
409 Conflict | 与已存在的对象/内容冲突或者操作行为与规则相冲突 |
422 Unprocessable | 操作不能进行 |
423 Locked | 帐号被锁定 |
429 Too Many Requests | 请求被限流 |
500 Server Error | 服务器出错 |
# 频率限制
注意：api 对单个帐号的请求是有频率限制的，请参阅有关的文档 API 限流
# 特殊声明
tloc 系列接口数据来源于离线计算，无法保证与其它接口同等的实时性、可用性，请业务侧使用时提前做好降级适配。
# 认证方式
每个 API 调用都需要认证，支持 Private_Key 方式。如果认证失败（比如认证码错误或者过期），会返回 401 错误，例如：
{
"message": "401 Unauthorized"
}
# Private_Key 方式
帐号的 Private_key 在https://git.tencent.com/profile/account设置。
- 方式一
使用 URL 请求参数private_token，例如：
GET https://git.tencent.com/api/v3/projects?private_token=ddwnTYP0bBSWaDPD7_NY
- 方式二
使用 HTTP_HEADER 的PRIVATE-TOKEN，例如：
curl --header "PRIVATE-TOKEN: ddwnTYP0bBSWaDPD7_NY" "https://git.tencent.com/api/v3/projects"
# 个人访问凭据 (Personal_access_token) 认证方式
请参阅有关的文档 Personal_access_token 文档
# 分页
所有获取列表的接口均支持分页 分页参数：
| 参数 | 含义 |
|---|---|
page | 页号（从1开始），默认值为1 |
per_page | 每页的项目数， (default: 20, max: 100) |
例如要获取项目中所有的 Commit，您需要按照页号循环，逐页获取
# 其他的分页方式
可在 Header 中获取以下分页参数
| Header | 描述 |
|---|---|
X-Total | 项目总数 |
X-Total-Pages | 总页数 |
X-Per-Page | 每页的项目数 |
X-Page | 当前页面的索引 (从 1 开始) |
X-Next-Page | 下一页的索引 |
X-Prev-Page | 上一页的索引 |
# iid 与 id 的区别
iid与id的含义完全不同
| 参数名 | 含义 | 备注说明 |
|---|---|---|
| id | 系统中全局唯一 | |
| iid | 项目中唯一，它的值会对应网页中的 URL 例如项目中的第 10 号 Issue | 使用数组iids[],需转义例：iids[]=1&iids[]=2 --> iids%5B%5D=1&iids%5B%5D=2 |
# full_path 说明
请求参数若为项目组或者项目全路径，应当保证进行 encodeURIComponent 编码； 支持 subgroup 之后，返回值 full_path 表示 项目组以及项目的全路径；返回值 path 保持原来含义，指的是项目组或者项目当前路径名称；
# namespace_full_path
| 参数名 | 含义 | 备注说明 |
|---|---|---|
| namespace_full_path | 项目组全路径 | 规则：进行 encodeURIComponent 编码/ 转换为 %2F；请求示例：root%2Fsubgroup01 (root/subgroup01) |
返回值说明：一个项目组根路径为 root，该路径下有一个 subgroup 名为 subgroup01，则返回值 path 为 root，full_path 为 root/subgroup01
# project_full_path
| 参数名 | 含义 | 备注说明 |
|---|---|---|
| project_full_path | 项目全路径 | 规则：进行 encodeURIComponent 编码/ 转换为 %2F；请求示例：root%2Fsubgroup01%2Fproject01 (root/subgroup01/project01) |
返回值说明：一个项目组根路径为 root，该路径下有一个 subgroup 名为 subgroup01，在 subgroup01 路径下有个项目 project01，则返回值 path 为 project01，path_with_namespace 为 root/subgroup01/project01
# SUDO 命令（系统管理员操作）
系统管理员可以在每一个请求中切换用户身份。只需要在请求中带有sudo参数或是使用 HTTP HEADER(SUDO)：
| 参数名 | 含义 |
|---|---|
sudo | 要切换的用户名 (username) 或 UID |
# 使用 URL 参数调用
GET https://git.tencent.com/api/v3/projects?private_token=ddwnTYP0bBSWaDPD7_NY&sudo=username
# 使用 HEADER 调用
curl --header "PRIVATE-TOKEN: ddwnTYP0bBSWaDPD7_NY" --header "SUDO: username" "https://git.tencent.com/api/v3/projects"