API

flask.ext.restplus

class flask_restplus.Api(app=None, version=u'1.0', title=None, description=None, terms_url=None, license=None, license_url=None, contact=None, contact_url=None, contact_email=None, authorizations=None, security=None, doc=u'/', default_id=<function default_id>, default=u'default', default_label=u'Default namespace', validate=None, tags=None, **kwargs)

The main entry point for the application. You need to initialize it with a Flask Application:

>>> app = Flask(__name__)
>>> api = Api(app)

Alternatively, you can use init_app() to set the Flask application after it has been constructed.

The endpoint parameter prefix all views and resources:

• The API root/documentation will be {endpoint}.root
• A resource registered as ‘resource’ will be available as {endpoint}.resource

Parameters:

• app (flask.Flask|flask.Blueprint) – the Flask application object or a Blueprint
• version (str) – The API version (used in Swagger documentation)
• title (str) – The API title (used in Swagger documentation)
• description (str) – The API description (used in Swagger documentation)
• terms_url (str) – The API terms page URL (used in Swagger documentation)
• contact (str) – A contact email for the API (used in Swagger documentation)
• license (str) – The license associated to the API (used in Swagger documentation)
• license_url (str) – The license page URL (used in Swagger documentation)
• endpoint (str) – The API base endpoint (default to ‘api).
• default (str) – The default namespace base name (default to ‘default’)
• default_label (str) – The default namespace label (used in Swagger documentation)
• default_mediatype (str) – The default media type to return
• validate (bool) – Whether or not the API should perform input payload validation.
• doc (str) – The documentation path. If set to a false value, documentation is disabled. (Default to ‘/’)
• decorators (list) – Decorators to attach to every resource
• catch_all_404s (bool) – Use handle_error() to handle 404 errors throughout your app
• url_part_order – A string that controls the order that the pieces of the url are concatenated when the full url is constructed. ‘b’ is the blueprint (or blueprint registration) prefix, ‘a’ is the api prefix, and ‘e’ is the path component the endpoint is added with
• errors (dict) – A dictionary to define a custom response for each exception or error raised during a request
• authorizations (dict) – A Swagger Authorizations declaration as dictionary

abort(code=500, message=None, **kwargs)

Properly abort the current request

add_resource(resource, *urls, **kwargs)

Register a Swagger API declaration for a given API Namespace

as_list(field)

Allow to specify nested lists for documentation

default_endpoint(resource, namespace=None)

Provide a default endpoint for a resource on a given namespace.

Endpoints are ensured not to collide.

deprecated(func)

Mark a resource or a method as deprecated

doc(shortcut=None, **kwargs)

Add some api documentation to the decorated object

errorhandler(exception)

Register an error handler for a given exception

expect(body, validate=None)

Specify the expected input model

extend(name, parent, fields)

Extend a model (Duplicate all fields)

handle_error(e)

Error handler for the API transforms a raised exception into a Flask response, with the appropriate HTTP status code and body.

Parameters:e (Exception) – the raised Exception object

header(name, description=None, **kwargs)

Specify one of the expected headers

inherit(name, parent, fields)

Inherit a modal (use the Swagger composition pattern aka. allOf)

init_app(app, **kwargs)

Allow to lazy register the API on a Flask application:

>>> app = Flask(__name__)
>>> api = Api()
>>> api.init_app(app)

Parameters:

• app (flask.Flask) – the Flask application object
• title (str) – The API title (used in Swagger documentation)
• description (str) – The API description (used in Swagger documentation)
• terms_url (str) – The API terms page URL (used in Swagger documentation)
• contact (str) – A contact email for the API (used in Swagger documentation)
• license (str) – The license associated to the API (used in Swagger documentation)
• license_url (str) – The license page URL (used in Swagger documentation)

marshal(data, fields)

A shortcut to the marshal helper

marshal_list_with(fields, **kwargs)

A shortcut decorator for marshal_with(as_list=True, code=code)

marshal_with(fields, as_list=False, code=200, description=None, **kwargs)

A decorator specifying the fields to use for serialization.

Parameters:

• as_list (bool) – Indicate that the return type is a list (for the documentation)
• code (integer) – Optionnaly give the expected HTTP response code if its different from 200

model(name=None, model=None, **kwargs)

Register a model

Model can be either a dictionary or a fields. Raw subclass.

parser()

Instanciate a RequestParser

render_doc()

Override this method to customize the documentation page

response(code, description, model=None, **kwargs)

Specify one of the expected responses

validate_payload(func)

Perform a payload validation on expected model

flask_restplus.marshal(data, fields, envelope=None)

Takes raw data (in the form of a dict, list, object) and a dict of fields to output and filters the data based on those fields.

Parameters:

• data – the actual object(s) from which the fields are taken from
• fields – a dict of whose keys will make up the final serialized response output
• envelope – optional key that will be used to envelop the serialized response

>>> from flask_restplus import fields, marshal
>>> data = { 'a': 100, 'b': 'foo' }
>>> mfields = { 'a': fields.Raw }

>>> marshal(data, mfields)
OrderedDict([('a', 100)])

>>> marshal(data, mfields, envelope='data')
OrderedDict([('data', OrderedDict([('a', 100)]))])

class flask_restplus.marshal_with(fields, envelope=None)

A decorator that apply marshalling to the return values of your methods.

>>> from flask_restplus import fields, marshal_with
>>> mfields = { 'a': fields.Raw }
>>> @marshal_with(mfields)
... def get():
...     return { 'a': 100, 'b': 'foo' }
...
...
>>> get()
OrderedDict([('a', 100)])

>>> @marshal_with(mfields, envelope='data')
... def get():
...     return { 'a': 100, 'b': 'foo' }
...
...
>>> get()
OrderedDict([('data', OrderedDict([('a', 100)]))])

see flask_restful.marshal()

class flask_restplus.marshal_with_field(field)

A decorator that formats the return values of your methods with a single field.

>>> from flask_restplus import marshal_with_field, fields
>>> @marshal_with_field(fields.List(fields.Integer))
... def get():
...     return ['1', 2, 3.0]
...
>>> get()
[1, 2, 3]

see flask_restful.marshal_with()

flask_restplus.abort(http_status_code, **kwargs)

Raise a HTTPException for the given http_status_code. Attach any keyword arguments to the exception for later processing.

exception flask_restplus.RestException(msg)

Base class for all Flask-Restplus Exceptions

exception flask_restplus.SpecsError(msg)

An helper class for incoherent specifications.

exception flask_restplus.ValidationError(msg)

An helper class for validation errors.

flask.ext.restplus.fields

All fields accept a required boolean and a description string in kwargs.

flask.ext.restplus.reqparse

flask.ext.restplus.inputs

flask.ext.restplus.mask

class flask_restplus.mask.Nested(name, fields)

fields

Alias for field number 1

name

Alias for field number 0

exception flask_restplus.mask.ParseError

Raise when the mask parsing failed

flask_restplus.mask.apply(data, mask, skip=False)

Apply a fields mask to the data.

If skip is True, missing field won’t appear in result

flask_restplus.mask.parse(mask)

Parse a fields mask. Expect something in the form:

{field,nested{nested_field,another},last}

External brackets are optionals so it can also be written:

field,nested{nested_field,another},last

All extras characters will be ignored.