Skip to content

RESTful API

hsfzxjy edited this page Jul 17, 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
}

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 /api/users/register/

Input
{
    username*: String,
    email*: Email,
    password*: String,
    password2*: 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 /api/users/

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 /api/notices/

Filters
  • has_read
  • category
  • ids: CommaSeparatedInt:用 id 列表筛选
Operations
  • list
  • retrieve

Clone this wiki locally