Skip to content
A Flask extension for creating simple ReSTful JSON APIs from SQLAlchemy models.
Branch: master
Clone or download
jfinkels Merge pull request #631 from jfinkels/case-insensitive-sorting
Allows client to request case-insensitive sorting
Latest commit 8e32477 Mar 25, 2017
Type Name Latest commit message Commit time
Failed to load latest commit information.
docs Allows client to request case-insensitive sorting Mar 25, 2017
examples Adds flake8 testing to travis Sep 7, 2016
requirements Moves requirements files into a directory. Dec 16, 2016
scripts Includes both wheel and source in release. Sep 8, 2016
tests Adds test for sorting on relationship attributes Mar 25, 2017
.coveragerc Reimplements search code using classes. May 10, 2016
.hound.yml Adds hound configuration file. Oct 6, 2016
.travis.yml Removes redundant entry in build matrix. Feb 28, 2017
CHANGES Allows client to request case-insensitive sorting Mar 25, 2017
LICENSE.BSD Dual-licensed under AGPLv3 and BSD. This is required to fix issue #14. Apr 9, 2012 Forgot to add in previous commit. Feb 4, 2016
setup.cfg Includes license files with built wheels. Feb 4, 2016



This is Flask-Restless, a Flask extension that creates URL endpoints that satisfy the requirements of the JSON API specification. It is compatible with models that have been defined using either SQLAlchemy or Flask-SQLAlchemy.

This document contains some brief instructions concerning installation of requirements, installation of this extension, configuration and usage of this extension, and building of documentation.

For more information, see the

Build status

Copyright license

The code comprising this program is copyright 2011 Lincoln de Sousa and copyright 2012, 2013, 2014, 2015, 2016 Jeffrey Finkelstein and contributors, and is dual-licensed under the following two copyright licenses:

  • the GNU Affero General Public License, either version 3 or (at your option) any later version
  • the 3-clause BSD License

For more information, see the files LICENSE.AGPL and LICENSE.BSD in this directory.

The documentation is licensed under the Creative Commons Attribution-ShareAlike 4.0 license.


This is a partial listing of the contents of this package.

  • LICENSE.AGPL - one possible copyright license under which this program is distributed to you (the GNU Affero General Public License version 3)
  • LICENSE.BSD - another possible copyright license under which this program is distributed to you (the 3-clause BSD License)
  • docs/ - the Sphinx documentation for Flask-Restless
  • examples/ - example applications of Flask-Restless
  • flask_restless/ - the Python package containing the extension
  • - indicates files to include when packaging Flask-Restless
  • - this file
  • - Python setuptools configuration file for packaging this extension
  • tests/ - unit tests for Flask-Restless

The flask_restless directory is a Python package containing the following files and directory:

  • - utility functions, mainly for performing introspection on SQLAlchemy objects
  • - contains the main class that end users will utilize to create ReSTful JSON APIs for their database models
  • - functions and classes that facilitate searching the database on requests that require a search
  • - basic serialization and deserialization for SQLAlchemy models
  • views/ - the view classes that implement the JSON API interface


This application can be used with any Python version that Flask supports, which currently includes versions 2.6, 2.7, 3.3, and 3.4. (Python 3.2 is not supported by Flask and therefore cannot be supported by Flask-Restless.)

This application requires the following libraries to be installed:

These requirements (and some additional optional packages) are also listed in the requirements/install.txt file. Using pip is probably the easiest way to install these:

pip install -r requirements/install.txt

Building as a Python egg

This package can be built, installed, etc. as a Python egg using the provided script. For more information, run

python --help

How to use

For information on how to use this extension, build the documentation here or view it on the Web.


If your Python interpreter is cpython, run:

pip install -r requirements/test-cpython.txt

Otherwise, if your Python interpreter is pypy, run:

pip install -r requirements/test-pypy.txt

To run the tests:

python test

Building documentation

Flask-Restless requires the following program and supporting library to build the documentation:

These requirements are also listed in the requirements/doc.txt file. Using pip is probably the easiest way to install these:

pip install -r requirements/doc.txt

The documentation is written for Sphinx in reStructuredText files in the docs/ directory. Documentation for each class and function is provided in the docstring in the code.

The documentation uses the Flask Sphinx theme. It is included as a git submodule of this project, rooted at docs/_themes. To get the themes, do

git submodule update --init

Now to build the documentation, run the command

python build_sphinx

in the top-level directory. The output can be viewed in a web browser by opening build/sphinx/html/index.html.


Please report any issues on the GitHub Issue Tracker.

To suggest a change to the code or documentation, please create a new pull request on GitHub. Contributed code must come with an appropriate unit test. Please ensure that your code follows PEP8, by running, for example, flake8 before submitting a pull request. Also, please squash multiple commits into a single commit in your pull request by rebasing onto the master branch.

By contributing to this project, you are agreeing to license your code contributions under both the GNU Affero General Public License, either version 3 or any later version, and the 3-clause BSD License, and your documentation contributions under the Creative Commons Attribution-ShareAlike License version 4.0, as described in the copyright license section above.


The artwork/flask-restless-small.svg and docs/_static/flask-restless-small.png are licensed under the Creative Commons Attribute-ShareAlike 4.0 license. The original image is a scan of a (now public domain) illustration by Arthur Hopkins in a serial edition of "The Return of the Native" by Thomas Hardy published in October 1878.

The artwork/flask-restless.svg and docs/_static/flask-restless.png are licensed under the Flask Artwork License.


Jeffrey Finkelstein

You can’t perform that action at this time.