Quickstart

Request parsing

Arguments can be retrieved using the following decorators:

• from_query
• from_form
• from_header
• from_cookie
• from_body

from flask import Flask
from flask_io import FlaskIO, fields

app = Flask(__name__)
io = FlaskIO(app)

@app.route('/')
@io.from_query('first_name', fields.String())
@io.from_query('limit', fields.Integer(missing=10))
@io.from_header('token', fields.String(required=True, load_from='Authorization'))
def find_users(first_name, limit, token):
    pass

Each parameter accepts either a Field or Schema to parse the arguments, the full documentation about those classes can be found here.

Output fields

Any object can be returned straight from the your function, Flask-IO will serialize the object for you. Complex object needs a Schema specified to be serialized, to specify a Schema you can use the decorator marshal_with

from flask import Flask
from flask_io import FlaskIO, fields

app = Flask(__name__)
io = FlaskIO(app)

class UserSchema(Schema):
    username = fields.String()

@app.route('/users/<username>')
@io.marshal_with(UserSchema)
def get_user(username):
    return User(username=username)

Python’s built-in types can be serialized without a Schema, for example, it is possible to return a dict without a Schema specified.

from flask import Flask
from flask_io import FlaskIO

app = Flask(__name__)
io = FlaskIO(app)

@app.route('/users/<username>')
def get_user(username):
    return dict(username=username)

A function does not even need to return an object, Flask-IO will return a response with status code 204 in this case.

from flask import Flask
from flask_io import FlaskIO

app = Flask(__name__)
io = FlaskIO(app)

@app.route('/users/<username>', methods=['DELETE'])
def delete_user(username):
    pass

Error handling

By default any error is serialized following the same structure.

{
    errors: [
        {
            "message": "User already exists: john123",
            "code": "user_already_exists",
            "field": "username",
            "location": "body"
        }
    ]
}

The error structure supports more than one error at the same time, usually argument validation returns more than one error.

Structure details:

• message is always present, it describes the error itself.
• code specifies a custom error code, it might be specified or not, it is up to you.
• field specifies the field name which is invalid.
• location specifies the location from where the error comes. Possible values are: query, form, header, cookie and body.

from flask import Flask
from flask_io import FlaskIO

app = Flask(__name__)
io = FlaskIO(app)

class UserSchema(Schema):
    username = fields.String(required=True, validate=validate.Length(min=6))

@app.route('/users>')
@io.from_body('user', UserSchema)
def add_user(user):
    pass

curl -X POST -H "Content-Type: application/json" http://localhost:5000/users -d '{"username":"john"}'

>>

{
    errors: [
        {
            "message": "Shorter than minimum length 6.",
            "field": "username",
            "location": "body"
        }
    ]
}