README.md

开放 API 服务

• 概况
• 授权
  • RTM token 授权
• 请求 Rate Limit
• 请求 & 响应风格

概况

开放 API (OpenAPI) 服务提供基于 HTTP 协议的 API 接口。

本文档描述的 API 版本为：1, 目前开放 API 的基地址 (base_url) 为：

https://api.bearychat.com/v1

包括以下几个模块：

• meta
• team: 团队相关
  • GET /team.info
• user: 用户相关
  • GET /user.info
  • GET /user.me
  • GET /user.list
• vchannel: 聊天会话相关
  • GET /vchannel.info
• channel: 讨论组相关
  • GET /channel.info
  • GET /channel.list
  • POST /channel.create
  • POST /channel.archive
  • POST /channel.unarchive
  • POST /channel.leave
  • POST /channel.join
  • POST /channel.invite
  • POST /channel.kick
• session_channel: 临时讨论组相关
  • GET /session_channel.info
  • GET /session_channel.list
  • POST /session_channel.create
  • POST /session_channel.archive
  • POST /session_channel.convert_to_channel
  • POST /session_channel.leave
  • POST /session_channel.invite
  • POST /session_channel.kick
• p2p: P2P 会话相关
  • GET /p2p.info
  • GET /p2p.list
  • POST /p2p.create
• message: 消息相关
  • POST /message.query
  • GET /message.info
  • POST /message.create
  • POST /message.delete
  • POST /message.update_text
• emoji: 团队自定义 emoji 相关
  • POST /emoji.list
• sticker: 团队 sticker 相关
  • POST /sticker.list
• rtm: RTM 相关
  • POST /rtm.start

所有接口都按照 OpenAPI 规格 进行记录，对应规格文件可以查看 swagger.yml

授权

如无特别说明，所有 API 接口都需要授权后才能访问。目前支持授权方式有：

• RTM token 授权

RTM token 授权

RTM token 目前可以通过创建 hubot 机器人获得

该授权模式下，请求方需要把 RTM token 值放到请求的 token 参数中，如：

POST https://api.bearychat.com/v1/rtm.start?token=your_rtm_token

或者

POST https://api.bearychat.com/v1/rtm.start
{
  "token": "your_rtm_token"
}

请求 Rate Limit

开放 API 采用以下 rate limit 策略：

• 未进行授权的请求，每小时可以请求 60 次
• 已进行授权的请求，每小时可以请求 1000 次

对应 rate limit 参数会在响应中给出：

x-ratelimit-remaining: 56
x-ratelimit-limit: 60
x-ratelimit-reset: 1489388400

• x-ratelimit-remaining: ratelimit 剩余数量
• x-ratelimit-limit: ratelimit 限制数量
• x-ratelimit-reset: ratelimit 重置 unix 时间戳

超出 ratelimit 限制会返回如下错误：

{
  "code": 13,
  "error": "请求太频繁，超过限制了，请慢点"
}

请求 & 响应风格

请求

如无特别说明，GET 请求参数需要放到 url query string 中：

GET https://api.bearychat.com/v1/meta?token=your_rtm_token

非 GET 请求参数需要使用 JSON 格式将参数放到请求体中：

POST https://api.bearychat.com/v1/rtm.start
Content-Type: application/json
{
  "token": "your_rtm_token"
}

响应

如无特别说明，开放 API 所有响应都将以 JSON 格式进行响应。