Skip to content

RESTful API

hsfzxjy edited this page Jul 27, 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,
    is_superuser!: Boolean,
    first_name: String,
    last_name: String,
    email: Email,
    date_joined!: DateTime,
    description: String,
    avatar_url: URL,
    education: String,
    major: 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/change_password/

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

API<User> /api/users/

Notes

<id> 可用 字符串 me 替换,以访问当前登录用户的信息。若未登录,返回 404。

Filters
  • username
  • first_name
  • last_name
Operations
  • list
  • retrieve
  • update
  • patch
Notes

自己只能更新自己。

GET /api/notices/categories/

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

GET /api/notices/categories_detail/

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