API 管理 / API 设计 / 接口声明

接口声明

文章内容

添加接口分组
添加接口
查看接口
编辑接口
删除接口

本文介绍如何通过 CODING 的 API 管理添加、管理接口，定义接口基本信息、接口路径、参数、返回值、数据结构等接口声明信息。

添加接口分组

登录团队的具体项目后，点击工作台左侧「API 管理」->「API 设计」。在「接口列表」页面点击+，在下拉菜单中根据实际需要点击「添加分组」，通过分组将项目接口进行分组管理。

如需创建子分组，在接口分组右侧点击···，在下拉菜单中点击「添加子分组」。

添加接口

在「API 设计」->「接口列表」页面可以根据实际需要在具体分组下点击「添加接口」创建接口。

添加单个 HTTP 接口

在「新建接口」页面选择「HTTP 接口」后点击「下一步」。

在「完善接口信息」环节的「基础信息」区域，定义接口名称、接口路径、请求寻址及接口描述。

配置接口路径时，选择 GET、POST 等接口调用方法后，建议按以下约定进行接口路径设计：

以斜杠/开头，全部使用小写字母，为提高接口路径的可读性、推荐使用短横线-、不使用下划线_，结尾不包含斜杠/。
可包含路径参数，路径参数需使用两个花括号括起来：{{参数名}}。例如：/api/v3/projects/{{id}}/repository/branches。
接口路径中不配置接口请求 Host（http 协议及域名），则在调试接口和执行用例时会依据做指向的地址或环境访问入口自动拼接；用户指定 Host 或使用变量定义后，系统将使用用户指定的 Host 而不会基于请求环境自动拼接。
「接口路径」用于定位资源，不应包含表示操作的动词，例如：“/api/getuser”、“/api/updateuser”、“api/deleteuser”包含了动词，配置不正确。
不应包含 Query 参数，即 URL 路径中“?”后的参数，查询参数请在「请求参数」区域的「查询参数」中配置。

在「请求参数」区域，配置查询参数、路径参数、请求体等请求参数。

查询参数：接口实际请求的 URL 中“?”后的参数。例如：实际请求 URL http://git.code.tencent.com/api/v3/projects/229888/issues?state=opened&labels=code,ifbook&page=1&per_page=20 中“?”后的参数为查询参数。

路径参数：系统自动提取「接口路径」中两个花括号{{}}括起来的参数。如需修改或添加该类型参数的名称，需在「基础信息」区域中的「接口路径」中进行配置。

请求体：HTTP 请求的 Body 部分。

请求体类型如下所示：

类型	说明
none	无 Body 参数，添加接口时默认为 none。
form-data	表单数据，请求头的 Content-Type 为 `multipart/form-data`。
x-www-form-urlencoded	将表单数据编码后作为请求的 Body 参数传输到服务器，请求头的 Content-Type 为 `application/x-www-form-urlencoded`。
JSON	发送请求时将数据编码为 JSON 格式并作为请求的 Body 参数传输到服务器，请求头的 Content-Type 为 `application/json`。
binary	发送请求时将二进制数据作为请求的 Body 参数传输到服务器。
text	发送请求时将纯文本格式数据作为请求的 Body 参数传输到服务器。
HTML	发送请求时将 HTML 格式数据作为请求的 Body 参数传输到服务器。
JS	发送请求时将 JS 格式数据作为请求的 Body 参数传输到服务器。
XML	发送请求时将 XML 格式数据作为请求的 Body 参数传输到服务器，请求头的 Content-Type 为 `application/xml`。

注意：

接口发送请求时会根据 Body 参数类型自动在请求 Header 加上对应的 Content-Type，无需手动设置。

若需要手动设置 Header 中的 Content-Type，则其值必须和 Body 参数类型相匹配，否则手动设置的 Content-Type 无效。例如，Body 参数类型为「form-data」，手动设置 Content-Type 的值为 multipart/form-data; charset=GBK 是有效的；但如果把 Content-Type 的值设置的和请求体格式不一致，系统会按照用户修改后的 Body 及 Content-Type 内容进行请求，但由于其内容不一致，将可能导致服务端无法正确获取请求详情等非预期错误。

请求头部：HTTP 头的一种，它可在 HTTP 请求中使用。

Cookie：支持设置接口请求时的 Cookie。

认证：接口调用过程通常需要连接认证。

请求认证的类型如下所示：

类型	说明
No Auth	表示当前接口无需 Auth 认证，添加接口默认认证类型为 No Auth。
Api Key	支持设置认证添加位置：查询参数或 Header。
Bearer Auth	支出输入 Token 类型凭证。
Basic Auth	支持指定用户名、密码格式的凭据。
Digest Auth	支持指定用户名、密码格式的凭据。 Digest Auth 默认会将响应信息添加到请求参数中并重试，允许关闭自动重试。