Skip to content

RESTful API

Jump to bottom
hsfzxjy edited this page Aug 15, 2017 · 12 revisions

Data Types

  • * 必填
  • ! 只读
  • ? 部分对象

type CommaSeparatedInt

示例：'1,2'。

type DateTime

ISO-8601 字符串，零时区。如：2017-07-17T07:12:29.181605Z。

type URL

alias of String.

type Email

alias of String.

type List

T 的数组。

type Page 

{
    count: Number,
    next: URL | null, // 下一页 URL
    previous: URL | null, // 上一页 URL
    results: List<T>
}

type User

{
    id!: Number,
    last_login!: DateTime | null,
    username: String,
    email: Email,
    description: String,
    avatar_url!: URL,
    address: String,
    site_url: URL,
    description: String
}

type Notice

{
    id!: Number,
    category!: String,
    message!: String,
    has_read: Boolean,
    created!: DateTime
}

type File

{
    id?: Number, // 不入库文件无此字段
    file: URL,
    mime_type: String
}

API

使用 JSON 交换数据。默认当输入有错误时，返回 Status Code 400 和详细错误信息。

标 API<T> <base> 的为类型 T 的 CRUD API，操作有如下几类：

  • list : GET <base> -> Page<T>
  • create : POST <base> -> T
  • retrieve: GET <base>/<id>/ -> T
  • update : PUT <base>/<id>/ -> T (输入为 T，完整更新对象)
  • patch : PATCH <base>/<id>/ -> T (输入为 T?，局部更新对象)
  • delete : DELETE <base>/<id>/

对于指定了 Filters 的 API，可以传递相应的 URL Parameters 筛选结果集。注意：

  • 对获取单个对象的操作使用 filters 时，可能会导致 404。
  • 筛选 Boolean 域时，传入字符串 True 或 False。

POST /files/upload/

上传文件。需以 multipart/form-data 的形式提交，文件的字段名为 file。

可选 URL 参数 store_db，若设置则表明此文件为需存入数据库的文件。

示例表单：

<!--入库-->
<form action="/files/upload/?store_db=1" method="post" enctype="multipart/form-data">
    <input type="file" name="file">
</form>
<!--不入库-->
<form action="/files/upload/" method="post" enctype="multipart/form-data">
    <input type="file" name="file">
</form>

Output

  • 403: 未登录
  • 200 -> File

POST /api/users/register/

用户注册。

Input
{
    username*: String,
    email*: Email,
    password*: String
}
Output
  • 404: 当前已有用户登录
  • 200 -> User: 自动将用户登入

POST /api/users/login/

用户登录。

Input
{
    username*: String,
    password*: String
}
Output
  • 404: 当前已有用户登录
  • 200 -> User

GET /api/users/logout/

用户登出。

Output
  • 403: 未登录
  • 200 -> String = 'OK'

POST /api/users/upload_avatar/

Input

multipart/form-data

file 域为文件。

Output

  • 403：未登录
  • 400：file 域缺失
  • 200 -> String：头像的 URL

POST /api/users/change_password/

Input
{
    old*: String,
    new1*: String,
    new2*: String
}
Output
  • 403: 未登录
  • 200 -> String = 'OK'

GET /api/users/reset_password/

请求发送重置密码的邮件。

邮件中会有一个指向回调的超链接，回调会带上一个 URL 参数 sign 作为数字签名（内含用户 ID 信息），用于下一步操作。

此接口每用户每分钟只能请求 1 次。

此接口用同步方式发邮件，会阻塞，设有 15 秒超时。

Query Params
  • callback: 回调 URL，会出现在邮件中供用户点击。
  • lookup：需要重置的用户的用户名或邮箱。
Output
  • 400：callback 不合法，lookup 不存在。
  • 429：请求过于频繁。
  • 500：邮件发送失败。
  • 200 -> String = 'OK'

POST /api/users/reset_password/

重置密码。

此接口中的 sign 参数即为上一步添加到回调 URL 上的 sign。

sign 参数时效为 5 分钟，超时后该数字签名即无效。

Input
{
    sign*: String,
    new_password*: String
}
Output
  • 400：数字签名损坏、超时，用户不存在，新密码不合法。
  • 200 -> String = 'OK'

GET /api/users/

获取用户列表。

Filters
  • username
  • first_name
  • last_name
Output
  • 200 -> Page<User>

GET /api/users/(<id>|me|n:<username>)/

获取用户信息。

Output
  • 404
  • 403: 未登录
  • 200 -> User

PATCH /api/users/me/

修改自己的用户信息。

Output
  • 403：未登录
  • 200 -> User

GET /api/users/(<id>|me|n:<username>)/followers/

获取粉丝列表。

Output
  • 403：未登录
  • 200 -> Page<User>

GET /api/users/(<id>|me|n:<username>)/following/

获取关注者列表。

Output
  • 403：未登录
  • 200 -> Page<User>

POST /api/users/(<id>|n:<username>)/follow/

关注一个人。关注自己或已关注时静默失败。

Output
  • 200 -> 'OK'

POST /api/users/(<id>|n:<username>)/unfollow/

取消关注一个人。静默失败同上。

Output
  • 200 -> 'OK'

GET /api/notices/categories/

Output
  • 200 -> List<String>: 分类列表

GET /api/notices/stats/

Output
type Category = {
    category: String,
    count: Number,
    unread: Number
}
  • 200 -> List<Category>：分类详情信息

GET /api/notices/mark_all_as_read/

  • 200 -> String = 'OK'

GET /api/notices//mark_read/

  • 200 -> String = 'OK'

API<Notice> /api/notices/

Filters
  • has_read
  • category
  • ids: CommaSeparatedInt：用 id 列表筛选
Operations
  • list
  • retrieve
Clone this wiki locally