入门

BeTalk REST API(基于使用的REST设计原则),允许访问BeTalk应用程序中使用HTTP方法传递的内容。

注:文档中的链接仅为示例参考,具体地址以实际项目为准。

1. 端点

在BeTalk上注册应用程序后调用BeTalk API请求数据非常便捷。本文档中列出的所有API URL相对于https://api.betalk.com/v1/。例如,/me/binders API调用访问使用https://api.betalk.com/v1/me/binders

BeTalk API请求端点(用于生产):https://api.betalk.com/v1/

BeTalk API请求端点(对于沙盒):https://apisandbox.betalk.com/v1/

2. 调用API

为了经过身份验证的调用API,需要调用访问令牌。你可以在请求报头加入访问令牌或如下利所示:

访问令牌发送的请求头:curl -H “Authorization: Bearer OAUTH-TOKEN” https://api.betalk.com/v1/me/binders

访问令牌发送的查询参数:GET HTTPS://api.BeTalk.com/v1/me/binders access_token = OAUTH-TOKEN …

所有的API是基于JSON,当请求包含数据需确保在报头中定义内容类型。

Content-Type: application/json

3. HTTP响应

HTTP响应可以被用来确定请求是否成功,并且将有助于确定错误的原因。当发生错误时,我们的API将返回适当的HTTP状态代码和一个错误消息说明。

HTTP代码 HTTP定义 响应代码 描述
200 OK RESPONSE_SUCCESS 该请求是成功的。
400 错误的请求 RESPONSE_ERROR_INVALID_REQUEST 端点不存在,或参数无效。无修改重试同样的请求将无法正常工作。
401 未经授权 RESPONSE_ERROR_INVALID_TOKEN 提供基于OAuth的认证授权头是无效的。应该重新验证用户。
403 被禁止 RESPONSE_ERROR_PERMISSION 错误的OAuth要求,你没有权限执行请求。无修改重试同样的请求将无法正常工作。
404 未找到 RESPONSE_ERROR_NOT_FOUND 您请求的内容不存在。
409 请求冲突 RESPONSE_ERROR_CONFLICT 因为冲突导致请求无法处理。
412 前提条件错误 ESPONSE_ERROR_PRECONDITION_FAILED 前提条件错误。
413 要求超限 RESPONSE_ERROR_EXCEED_LIMIT 请求实体超限。
429 过多的请求 RESPONSE_ERROR_TOO_MANY_REQUESTS 超过BeTalk请求数量的限制。
500 内部服务器错误 RESPONSE_ERROR_FAILED 内部服务器错误,我们正在处理。
503 暂停服务 RESPONSE_ERROR_SERVICE_UNAVAILABLE 这项服务暂时关闭。