Navigation

Flask-RESTful provides an easy way to control what data you actually render in
your response. With the fields module, you can use whatever objects (ORM
models/custom classes/etc.) you want in your resource. fields also lets you
format and filter the response so you don’t have to worry about exposing
internal data structures.

It’s also very clear when looking at your code what data will be rendered and
how it will be formatted.

You can define a dict or OrderedDict of fields whose keys are names of
attributes or keys on the object to render, and whose values are a class that
will format & return the value for that field. This example has three fields:
two are String and one is a DateTime,
formatted as an RFC 822 date string (ISO 8601 is supported as well)

fromflask_restfulimportResource,fields,marshal_withresource_fields={'name':fields.String,'address':fields.String,'date_updated':fields.DateTime(dt_format='rfc822'),}classTodo(Resource):@marshal_with(resource_fields,envelope='resource')defget(self,**kwargs):returndb_get_todo()# Some function that queries the db

This example assumes that you have a custom database object (todo) that
has attributes name, address, and date_updated. Any additional
attributes on the object are considered private and won’t be rendered in the
output. An optional envelope keyword argument is specified to wrap the
resulting output.

The decorator marshal_with is what actually takes your data object and
applies the field filtering. The marshalling can work on single objects,
dicts, or lists of objects.

Note

marshal_with is a convenience decorator, that is functionally
equivalent to

Sometimes you have your own custom formatting needs. You can subclass the
fields.Raw class and implement the format function. This is especially
useful when an attribute stores multiple pieces of information. e.g. a
bit-field whose individual bits represent distinct values. You can use fields
to multiplex a single attribute to multiple output values.

This example assumes that bit 1 in the flags attribute signifies a
“Normal” or “Urgent” item, and bit 2 signifies “Read” or “Unread”. These
items might be easy to store in a bitfield, but for a human readable output
it’s nice to convert them to seperate string fields.

Flask-RESTful includes a special field, fields.Url, that synthesizes a
uri for the resource that’s being requested. This is also a good example of how
to add data to your response that’s not actually present on your data object.:

classRandomNumber(fields.Raw):defoutput(self,key,obj):returnrandom.random()fields={'name':fields.String,# todo_resource is the endpoint name when you called api.add_resource()'uri':fields.Url('todo_resource'),'random':RandomNumber,}

By default fields.Url returns a relative uri. To generate an absolute uri
that includes the scheme, hostname and port, pass the keyword argument
absolute=True in the field declaration. To override the default scheme,
pass the scheme keyword argument:

This example uses two Nested fields. The Nested constructor takes a
dict of fields to render as sub-fields. The important difference between
the Nested constructor and nested dicts (previous example), is the context
for attributes. In this example, billing_address is a complex object that
has its own fields and the context passed to the nested field is the sub-object
instead of the original data object. In other words:
data.billing_address.addr1 is in scope here, whereas in the previous
example data.addr1 was the location attribute. Remember: Nested and
List objects create a new scope for attributes.