API

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

class flask_restless.APIManager(app=None, **kw)

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.

app is the flask.Flask object containing the user’s Flask application.

session is the sqlalchemy.orm.session.Session object in which changes to the database will be made.

flask_sqlalchemy_db is the flask_sqlalchemy.SQLAlchemy object with which app has been registered and which contains the database models for which API endpoints will be created.

If flask_sqlalchemy_db is not None, session will be ignored.

For example, to use this class with models defined in pure SQLAlchemy:

from flask import Flask
from flask_restless import APIManager
from sqlalchemy import create_engine
from sqlalchemy.orm.session import sessionmaker

engine = create_engine('sqlite:////tmp/mydb.sqlite')
Session = sessionmaker(bind=engine)
mysession = Session()
app = Flask(__name__)
apimanager = APIManager(app, session=mysession)

and with models defined with Flask-SQLAlchemy:

from flask import Flask
from flask_restless import APIManager
from flask_sqlalchemy import SQLAlchemy

app = Flask(__name__)
db = SQLALchemy(app)
apimanager = APIManager(app, flask_sqlalchemy_db=db)
init_app(app, session=None, flask_sqlalchemy_db=None, preprocessors=None, postprocessors=None)

Stores the specified flask.Flask application object on which API endpoints will be registered and the sqlalchemy.orm.session.Session object in which all database changes will be made.

session is the sqlalchemy.orm.session.Session object in which changes to the database will be made.

flask_sqlalchemy_db is the flask_sqlalchemy.SQLAlchemy object with which app has been registered and which contains the database models for which API endpoints will be created.

If flask_sqlalchemy_db is not None, session will be ignored.

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

To use this method with pure SQLAlchemy, for example:

from flask import Flask
from flask_restless import APIManager
from sqlalchemy import create_engine
from sqlalchemy.orm.session import sessionmaker

apimanager = APIManager()

# later...

engine = create_engine('sqlite:////tmp/mydb.sqlite')
Session = sessionmaker(bind=engine)
mysession = Session()
app = Flask(__name__)
apimanager.init_app(app, session=mysession)

and with models defined with Flask-SQLAlchemy:

from flask import Flask
from flask_restless import APIManager
from flask_sqlalchemy import SQLAlchemy

apimanager = APIManager()

# later...

app = Flask(__name__)
db = SQLALchemy(app)
apimanager.init_app(app, flask_sqlalchemy_db=db)

postprocessors and preprocessors must be dictionaries as described in the section Request preprocessors and postprocessors. These preprocessors and postprocessors will be applied to all requests to and responses from APIs created using this APIManager object. The preprocessors and postprocessors given in these keyword arguments will be prepended to the list of processors given for each individual model when using the create_api_blueprint() method (more specifically, the functions listed here will be executed before any functions specified in the create_api_blueprint() method). For more information on using preprocessors and postprocessors, see Request preprocessors and postprocessors.

New in version 0.13.0: Added the preprocessors and postprocessors keyword arguments.

create_api(*args, **kw)

Creates and registers a ReSTful API blueprint on the flask.Flask application specified in the constructor of this class.

The positional and keyword arguments are passed directly to the create_api_blueprint() method, so see the documentation there.

This is a convenience method for the following code:

blueprint = apimanager.create_api_blueprint(*args, **kw)
app.register_blueprint(blueprint)

Changed in version 0.6: The blueprint creation has been moved to create_api_blueprint(); the registration remains here.

create_api_blueprint(model, app=None, methods=frozenset({'GET'}), url_prefix='/api', collection_name=None, allow_patch_many=False, allow_delete_many=False, allow_functions=False, exclude_columns=None, include_columns=None, include_methods=None, validation_exceptions=None, results_per_page=10, max_results_per_page=100, post_form_preprocessor=None, preprocessors=None, postprocessors=None, primary_key=None, serializer=None, deserializer=None)

Creates and returns a ReSTful API interface as a blueprint, but does not register it on any flask.Flask application.

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.__tablename__. (If any black magic was performed on model.__tablename__, this will be reflected in the endpoint URL.) For more information, see Collection name.

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 SQLAlchemy model class for which a ReSTful interface will be created. Note this must be a class, not an instance of a class.

app is the Flask object on which we expect the blueprint created in this method to be eventually registered. If not specified, the Flask application specified in the constructor of this class is used.

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

  • If :http:method:`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 :http:method:`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 :http:method:`delete` is in this list, the API will allow deletion of a single instance of the model per request.
  • If :http:method:`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 :http:method:`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 :http:patch:`/api/<collection_name>?q=<searchjson>` 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.

If allow_delete_many is True, then requests to :http:delete:`/api/<collection_name>?q=<searchjson>` will attempt to delete each instance of the model that matches 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 :http:get:`/api/eval/<collection_name>` 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.

If either include_columns or exclude_columns is not None, exactly one of them must be specified. If both are not None, then this function will raise a IllegalArgumentError. exclude_columns must be an iterable of strings specifying the columns of model which will not be present in the JSON representation of the model provided in response to :http:method:`get` requests. Similarly, include_columns specifies the only columns which will be present in the returned dictionary. In other words, exclude_columns is a blacklist and include_columns is a whitelist; you can only use one of them per API endpoint. If either include_columns or exclude_columns contains a string which does not name a column in model, it will be ignored.

If you attempt to either exclude a primary key field or not include a primary key field for :http:method:`post` requests, this method will raise an IllegalArgumentError.

If include_columns is an iterable of length zero (like the empty tuple or the empty list), then the returned dictionary will be empty. If include_columns is None, then the returned dictionary will include all columns not excluded by exclude_columns.

If include_methods is an iterable of strings, the methods with names corresponding to those in this list will be called and their output included in the response.

See Specifying which columns are provided in responses for information on specifying included or excluded columns on fields of related models.

results_per_page is a positive integer which represents the default number of results which are returned per page. Requests made by clients may override this default by specifying results_per_page as a query argument. max_results_per_page is a positive integer which represents the maximum number of results which are returned per page. This is a “hard” upper bound in the sense that even if a client specifies that greater than max_results_per_page should be returned, only max_results_per_page results will be returned. For more information, see Server-side pagination.

Deprecated since version 0.9.2: The post_form_preprocessor keyword argument is deprecated in version 0.9.2. It will be removed in version 1.0. Replace code that looks like this::

manager.create_api(Person, post_form_preprocessor=foo)

with code that looks like this:

manager.create_api(Person, preprocessors=dict(POST=[foo]))

See Request preprocessors and postprocessors for more information and examples.

post_form_preprocessor is a callback function which takes POST input parameters loaded from JSON and enhances them with other key/value pairs. The example use of this is when your model requires to store user identity and for security reasons the identity is not read from the post parameters (where malicious user can tamper with them) but from the session.

preprocessors is a dictionary mapping strings to lists of functions. Each key is the name of an HTTP method (for example, 'GET' or 'POST'). Each value is a list of functions, each of which will be called before any other code is executed when this API receives the corresponding HTTP request. The functions will be called in the order given here. The postprocessors keyword argument is essentially the same, except the given functions are called after all other code. For more information on preprocessors and postprocessors, see Request preprocessors and postprocessors.

primary_key is a string specifying the name of the column of model to use as the primary key for the purposes of creating URLs. If the model has exactly one primary key, there is no need to provide a value for this. If model has two or more primary keys, you must specify which one to use.

serializer and deserializer are custom serialization functions. The former function must take a single argument representing the instance of the model to serialize, and must return a dictionary representation of that instance. The latter function must take a single argument representing the dictionary representation of an instance of the model and must return an instance of model that has those attributes. For more information, see Custom serialization.

New in version 0.17.0: Added the serializer and deserializer keyword arguments.

New in version 0.16.0: Added the app and allow_delete_many keyword arguments.

New in version 0.13.0: Added the primary_key keyword argument.

New in version 0.10.2: Added the include_methods keyword argument.

Changed in version 0.10.0: Removed authentication_required_for and authentication_function keyword arguments.

Use the preprocesors and postprocessors keyword arguments instead. For more information, see Requiring authentication for some methods.

New in version 0.9.2: Added the preprocessors and postprocessors keyword arguments.

New in version 0.9.0: Added the max_results_per_page keyword argument.

New in version 0.7: Added the exclude_columns keyword argument.

New in version 0.6: This functionality was formerly in create_api(), but the blueprint creation and registration have now been separated.

New in version 0.6: Added the results_per_page keyword argument.

New in version 0.5: Added the include_columns and validation_exceptions keyword argument.

New in version 0.4: Added the allow_functions, allow_patch_many, authentication_required_for, authentication_function, and collection_name keyword arguments.

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

flask_restless.url_for(model, instid=None, relationname=None, relationinstid=None, _apimanager=None, **kw)

Returns the URL for the specified model, similar to flask.url_for().

model is a SQLAlchemy model class. This should be a model on which APIManager.create_api_blueprint() (or APIManager.create_api()) has been invoked previously. If no API has been created for it, this function raises a ValueError.

If _apimanager is not None, it must be an instance of APIManager. Restrict our search for endpoints exposing model to only endpoints created by the specified APIManager instance.

instid, relationname, and relationinstid allow you to get a more specific sub-resource.

For example, suppose you have a model class Person and have created the appropriate Flask application and SQLAlchemy session:

>>> manager = APIManager(app, session=session)
>>> manager.create_api(Person, collection_name='people')
>>> url_for(Person, instid=3)
'http://example.com/api/people/3'
>>> url_for(Person, instid=3, relationname=computers)
'http://example.com/api/people/3/computers'
>>> url_for(Person, instid=3, relationname=computers, relationinstid=9)
'http://example.com/api/people/3/computers/9'

The remaining keyword arguments, kw, are passed directly on to flask.url_for().

class flask_restless.ProcessingException(description='', code=400, *args, **kwargs)

Raised when a preprocessor or postprocessor encounters a problem.

This exception should be raised by functions supplied in the preprocessors and postprocessors keyword arguments to APIManager.create_api. When this exception is raised, all preprocessing or postprocessing halts, so any processors appearing later in the list will not be invoked.

code is the HTTP status code of the response supplied to the client in the case that this exception is raised. description is an error message describing the cause of this exception. This message will appear in the JSON object in the body of the response to the client.