API

This part of the documentation documents all the public classes and functions in Flask-Restless.

class flask.ext.restless.APIManager(app=None, flask_sqlalchemy_db=None)

Provides a method for creating a public ReSTful JSOn API with respect to a given Flask application object.

The Flask object can be specified in the constructor, or after instantiation time by calling the init_app() method. In any case, the application object must be specified before calling the create_api() method.

init_app(app, flask_sqlalchemy_db)

Stores the specified flask.Flask application object on which API endpoints will be registered and the flask.ext.sqlalchemy.SQLAlchemy object which contains the models which will be exposed.

This is for use in the situation in which this class must be instantiated before the Flask application has been created. For example:

import flask
import flask.ext.restless
import flask.ext.sqlalchemy

apimanager = flask.ext.restless.APIManager()

# later...

app = flask.Flask(__name__)
db = flask.ext.sqlalchemy.SQLALchemy(app)
apimanager.init_app(app, db)

create_api(model, methods=frozenset(['GET']), url_prefix='/api', collection_name=None, allow_patch_many=False, allow_functions=False, authentication_required_for=None, authentication_function=None, include_columns=None, validation_exceptions=None)

Creates a ReSTful API interface as a blueprint and registers it on the flask.Flask application specified in the constructor to this class.

The endpoints for the API for model will be available at <url_prefix>/<collection_name>. If collection_name is None, the lowercase name of the provided model class will be used instead, as accessed by model.__name__. (If any black magic was performed on model.__name__, this will be reflected in the endpoint URL.)

This function must be called at most once for each model for which you wish to create a ReSTful API. Its behavior (for now) is undefined if called more than once.

This function returns the flask.Blueprint object which handles the endpoints for the model. The returned Blueprint has already been registered with the Flask application object specified in the constructor of this class, so you do not need to register it yourself.

model is the flask.ext.restless.Entity class for which a ReSTful interface will be created. Note this must be a class, not an instance of a class.

methods specify the HTTP methods which will be made available on the ReSTful API for the specified model, subject to the following caveats:

• If GET is in this list, the API will allow getting a single instance of the model, getting all instances of the model, and searching the model using search parameters.
• If PATCH is in this list, the API will allow updating a single instance of the model, updating all instances of the model, and updating a subset of all instances of the model specified using search parameters.
• If DELETE is in this list, the API will allow deletion of a single instance of the model per request.
• If POST is in this list, the API will allow posting a new instance of the model per request.

The default set of methods provides a read-only interface (that is, only GET requests are allowed).

collection_name is the name of the collection specified by the given model class to be used in the URL for the ReSTful API created. If this is not specified, the lowercase name of the model will be used.

url_prefix the URL prefix at which this API will be accessible.

If allow_patch_many is True, then requests to /api/ will attempt to patch the attributes on each of the instances of the model which match the specified search query. This is False by default. For information on the search query parameter q, see Making search queries.

validation_exceptions is the tuple of possible exceptions raised by validation of your database models. If this is specified, validation errors will be captured and forwarded to the client in JSON format. For more information on how to use validation, see Capturing validation errors.

If allow_functions is True, then requests to /api/eval/ will return the result of evaluating SQL functions specified in the body of the request. For information on the request format, see Function evaluation. This if False by default. Warning: you must not create an API for a model whose name is 'eval' if you set this argument to True.

authentication_required_for is a list of HTTP method names (for example, ['POST', 'PATCH']) for which authentication must be required before clients can successfully make requests. If this keyword argument is specified, authentication_function must also be specified. For more information on requiring authentication, see Specifying which columns are provided in responses.

authentication_function is a function which accepts no arguments and returns True if and only if a client is authorized to make a request on an endpoint.

include_columns is a list of strings which name the columns of model which will be included in the JSON representation of that model provided in response to GET requests. Only the named columns will be included. If this list includes a string which does not name a column in model, it will be ignored.

New in version 0.5: Added the include_columns keyword argument.

New in version 0.5: Added the validation_exceptions keyword argument.

New in version 0.4: Added the authentication_required_for keyword argument.

New in version 0.4: Added the authentication_function keyword argument.

New in version 0.4: Added the allow_functions keyword argument.

Changed in version 0.4: Force the model name in the URL to lowercase.

New in version 0.4: Added the allow_patch_many keyword argument.

New in version 0.4: Added the collection_name keyword argument.