概述

起步

闲言社区 OpenAPI 将部分网站服务封装成一系列 API(Application Programming Interface,应用编程接口)开放出来,供第三方开发者使用。

闲言社区 OpenAPI 遵循 REST 标准进行设计。

所有的 OpenAPI 请求地址都是 可预期的 以及 面向资源 的,并且使用规范的 HTTP 响应代码 来标识请求结果的正确与错误信息。

所有的 OpenAPI 请求都会以规范友好的 JSON 对象格式返回(包括错误信息),并且使用「个人访问令牌」Personal Access Token 作为鉴权方法。

所有请求和响应的编码均为 UTF-8

调用说明

基础地址(Base URL)为:

https://bbs.90so.net/api

Oauth 地址(Oauth URL)为:

https://bbs.90so.net/oauth

认证方式

OAuth2 token (sent in a header)

请求 API 时,增加 Authorization Header

Authorization: Bearer {token}

请求

所有的请求方式(Method)均与动词相关:

  • GET:获取资源
  • POST:创建资源
  • PUT:替换资源或集合
  • PATCH:通过部分 JSON 数据更新资源
  • DELETE:删除资源
  • OPTIONS:获取客户端能对资源做什么操作的信息

参数传入方式

如无特别说明,GET 请求参数需要放到 Url Query String 中。

POST/PUT/PATCH 请求参数建议使用 JSON 格式将参数放到请求体中。

请求限制

为了防止拒绝服务攻击,闲言社区 OpenAPI 制定了一定的限流策略,规则如下:

  • 访问频率限制,每分钟可请求 10 次
  • 登录相关频率限制,每分钟可请求 6 次

为了方便您查询当前限流的情况,你可通过响应的 Header 的 Rate Limit 参数查看,参数如下:

  • X-RateLimit-Limit:限制可请求数量
  • X-RateLimit-Remaining:剩余可请求数量
  • Retry-After:触达限流后需要等待重置的时间(秒)
  • X-RateLimit-Reset:重置限制次数时间(秒)

范例:

X-RateLimit-Limit: 10
X-RateLimit-Remaining: 9

超出限流限制会返回如下错误:

Header:

X-RateLimit-Limit:10
X-RateLimit-Remaining:0
Retry-After: 27
X-RateLimit-Reset:1584516281
Date:Wed, 18 Mar 2020 15:24:14 GMT

{
    "message": "Too Many Attempts."
}

响应

错误

闲言社区 OpenAPI 使用标准 HTTP 响应码(Status Code)来表示 API 请求。

通常,状态码:

  • 2xx 代表成功响应
  • 4xx 代表失败响应,并给出失败原因
  • 5xx 代表闲言社区服务端内部错误

状态码说明

状态码 描述
200 更新/获取资源成功
201 创建资源成功
204 删除资源成功
400 业务错误,具体参见下方业务错误代码
401 认证失败,请检查认证相关参数是否有误
403 无权限调用接口,如:未开通 API 功能
404 资源不存在
405 接口请求方式 Method 有误
422 请求参数校验失败
429 触达限流限制
500 服务器应用发生了错误
502 服务器无法连接
503 服务器暂不可用
504 服务器连接超时

错误返回格式

{
    "message": "Unauthenticated."
}
错误原因 状态码 错误描述
因为无效的 API 密钥和令牌
无权限请求接口
401 无法使用无效的 API 密钥和令牌
进行身份验证
{
    "message": "The given data was invalid.",
    "errors": {
        "name": [
            "用户名已被占用,请重新填写"
        ]
    }
}
错误原因 状态码 错误描述
用户名已被占用 422 用户名已被占用,请更改后重新提交

字段类型

在文档中,我们将使用许多不同类型的数据。您可以在下方的说明列表找到它们的解释及含义。

类型 定义 范例
integer 整数,不带小数的数字。 1234
float 浮点数,带小数的数字。 1234.12
string 字符串是用于表示文本的字符序列。 "闲言"
boolean 布尔值,是 true 或 false 中的一个,所对应的关系就是真与假的概念。 true
date 表示日期的字符串。 "2019-09-01"
datetime 表示日期和时间的字符串。 "2019-09-10 12:23:01"
list() 列表,该列表为数组,数组中的每一项的类型由括号内的字段类型决定。 ["item1", "item2", "item3"]
object() 资源,括号内的资源实体不在此处展开,可从对应的资源 XX 对象中找到。 {"id": 1,"name": "NPC小明"}

加入我们

{warning} 为了避免广告及不看文档的用户,我们目前还没有任何的官方交流群,可能以后会有,但现在还没有。

你有以下两种方式加入到我们中来:

打赏支持

我们没有收费服务,你如果觉得你从中获益,你可以 打赏 来支持我们。