How to read API document

This is a guide written for the API users, describes how to read API documentation generated by Flask-Restaction.
There will be no complex concepts and can be grasped within ten minutes.

UI Layout

The sidebar can be divided into 4 parts:

1. Desc

   Description of the API, it contains shared schemas, error informations and so on.

2. Meta

   A text in JSON format, it contains all meta data of API.

3. Roles

   Shows all roles and it's permission.

4. Resources

   All resources, this is the main content of API document.

URL rules

API is divided into many resources, each resources contains some actions.

Resource

Represents a kind of resources.

Action

Manipulation of resources, eg: get, post, delete, get_list, post_login.

In General, Use Resource.Action to represents a interface, eg: user.post_login.

In order to convert Resource.Action to URL, replace . to /, then remove the part before _ in Action.

For example: user.post_login convert to user/login.

If API not deployed in root path of the website, eg: /api, then you should add prefix /api to URL, that is /api/user/login.

Schema

Schema is a JSON text used to describe request data and response content.

The Schema's structure in API document is the same as real data, {} represents object, [] represents array.

Shared Schema:
In Desc part, there is a "Shared" section, which describe the shared schemas of the API. And each resource may has a "Shared" section, which describe the shared schema inside the resource.

Interface

Let's starts with login inderface: user.post_login

In the "Shared" section of User resource, @user describe a shared schema inside User.

@user

{
    "date_create?datetime&optional": "date created",
    "date_modify?datetime&optional": "date modified",
    "id?str": "user ID",
    "lastlogin_date?datetime&optional": "last login date",
    "role?str": "user role"
}

In the login inderface, Input and Output describe request data and response content, Error describe errors the server may responses.

Input

{
    "account?str": "user ID or email",
    "password?str": "password"
}

The request data is account and password, both is string type.

Output

@user

The response content is @user which described in "Shared" section.

Error

{
    "403.UserNotFound": "user not found",
    "403.WrongPassword": "password error"
}

If user not exists, the server will response error below, others errors' structure is similar:

{
    "status": 403,
    "error": "UserNotFound",
    "message": "user not found"
}

Mixin Schema

Let's use a interface which return a list of authors' article for example.

@pagging

{
    "page?int&min=1&default=1": "page number",
    "per_page?int&min=1&max=100&default=10": "page size"
}

Input

{
    "$self@pagging": "pagging",
    "author?str": "author",
    "tag?str&optional": "article tag"
}

Here $self@pagging means mixin @pagging into Input, and the Input is equal to:

{
    "page?int&min=1&default=1": "page number",
    "per_page?int&min=1&max=100&default=10": "page size",
    "author?str": "author",
    "tag?str&optional": "article tag"
}

Field Description

The syntax of field description is name?validator&param=value&...

name: field name
validator: can be understood as data type, eg: str,int,datetime
param: param of validator, eg: optional, default

For example:

"lastlogin_date?datetime&optional": "last login date"

Means: field name is lastlogin_date, type is datetime, the field is optional.