Syntaxic sugar

One of the purpose of Flask-Restplus is to provide some syntaxic sugar of Flask-Restful.

Route with decorator

The Api class has a route() decorator used to route API’s endpoint.

When with Flask-Restful you were writting :

class MyResource(Resource):
    def get(self, id):
        return {}

api.add_resource('/my-resource/<id>', MyResource.as_view('my-resource'))

With Flask-Restplus, you can write:

@api.route('/my-resource/<id>', endpoint='my-resource')
class MyResource(Resource):
    def get(self, id):
        return {}

You can optionnaly provide class-wide documentation:

@api.route('/my-resource/<id>', endpoint='my-resource', doc={params:{'id': 'An ID'}})
class MyResource(Resource):
    def get(self, id):
        return {}

But it will be easier to read with two decorators for the same effect:

@api.route('/my-resource/<id>', endpoint='my-resource')
@api.doc(params={'id': 'An ID'})
class MyResource(Resource):
    def get(self, id):
        return {}

The namespace object provide the same feature:

ns = api.namespace('ns', 'Some namespace')

# Will ba available to /api/ns/my-resource/<id>
@ns.route('/my-resource/<id>', endpoint='my-resource')
class MyResource(Resource):
    def get(self, id):
        return {}

All routes within a namespace are prefixed with the namespace name.

abort shortcut

You can use the Api.abort() method to abort a request. This shortcut always serialize the response in the right format.

@api.route('/failure')
class MyResource(Resource):
    def get(self):
        api.abort(403)

    def post(self):
        api.abort(500, 'Some custom message')

parser shortcut

You can use the Api.parser() shortcut to obtain a RequestParser instance.

parser = api.parser()
parser.add_argument('param', type=str, help='Some parameter')

marshal shortcut

You can use the Api.marshal() shortcut to serialize your objects.

return api.marshal(todos, fields), 201