订阅蜂 REST API 文档格式主要如下：

• 请求：

  • 基本信息

  • 请求头

  • 路径参数

  • 查询参数

  • 请求体

• 响应：

  • 响应体

  • 错误码

1. 基本信息

   介绍调用 API 所需要的请求方式、路径、访问凭证和权限等信息。

   • HTTP URL：订阅蜂 REST API 的URL。

   • HTTP Method：订阅蜂 REST API 仅支持 HTTPS 协议和标准 HTTP 方法，如 GET、POST 等。

   • 权限要求：调用 API 所需要权限，多个权限的关系为或，申请其中任一权限即可。

   • 字段权限要求：请求返回结果中如需使用部分字段，需要特别申请权限。一般敏感字段的读取需要申请这类权限。

2. 请求参数

   调用 API 的详细入参说明，参数使用风格遵循 RESTFul，请注意不同参数在调用时的位置。

   • 请求头：这部分参数需要放在 HTTP 请求的 Header 中，主要包含调用 API 所需要使用的访问凭证（access token）以及 HTTP Content-Type。

   • 路径参数：这部分参数需要放置在 URL 中，在文档中一般以:开头。

   • 查询参数：这部分参数需要在 URL 后使用?进行连接，多个查询参数间以&分隔。

   • 请求体：这部分参数需要放在 HTTP 请求的 Body 中，一般为 JSON 格式。

3. 响应

   调用 API 的返回值。

   • 响应体：一次 API 调用后，HTTP 响应中 Body 部分的内容。

   • 错误码：调用该 API 可能返回的错误码解释以及排查建议。

二、API 调用流程

如下图所示，在调用订阅蜂REST API 前，您需要完成以下2个准备工作：

1. 申请 API 调用所需要的权限

   API 调用中的权限主要分两部分，一个是调用权限，另一个是字段权限。没有 API 调用权限时， API 的请求会被拒绝。没有敏感字段读取权限时，返回的响应体中将排除敏感字段。权限的申请请参考 应用权限。

2. 获取 API 调用所需要的凭证

   订阅蜂REST API 使用的是租户访问凭证，API 调用需要将凭证放入 Header 中，使用语法Authorization: bearer {实际的access token} 进行调用。凭证的获取和使用请参考 [API 授权]

三、API 调用方式

调用服务端接口时，需要使用 HTTPS 协议、JSON 数据格式、UTF8 编码。请求需要把访问凭证access token 放到 Header 的 Authorization 中。示例如下：

curl -X POST https://rest.dingyuefeng.com/v1/employees/department/1590485735467354627
-H 'content-type:application/json' \
-H 'Authorization:Bearer <这里替换为对应的access token>' \
-d '{
    "name": "Julia Zhou",
    "gender": "女",
    "number": "006",
    "phoneNumber": "18699999999",
    "position": "销售经理",
    "roleName": "默认角色",
    "status": "在职",
}' 

四、API 响应结果说明

绝大多数 API 的响应体结构包括code、message、data三个部分。

code 为错误码，message为错误信息，data 为 API 的调用结果。默认请求成功时，code 为 200，message 为 "请求成功"。"data" 在一些操作类 API 的返回中可能不存在。

例如：

{
	"code": 200,
	"success": true,
	"message": "请求成功",
	"data": {
		// 响应的具体数据内容
	}
}

{
	"success": false,
    "code": 14300405,
    "message": "员工名称为必输入，请输入员工名称！",
	"data": null
}

注意：请求失败时可以根据 code 的值到API 资源代码查看