Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

542 lines (354 sloc) 13.012 kB

Format of requests and responses

Requests and responses are all in JSON format, so the mimetype is :mimetype:`application/json`. Ensure that requests you make have the correct mimetype and/or content type.

Suppose we have the following Flask-SQLAlchemy models (the example works with pure SQLALchemy just the same):

from flask import Flask
from flask.ext.sqlalchemy import SQLAlchemy

app = Flask(__name__)
app.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite:////tmp/test.db'
db = SQLAlchemy(app)

class Person(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    name = db.Column(db.Unicode, unique=True)
    birth_date = db.Column(db.Date)
    computers = db.relationship('Computer',

class Computer(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    name = db.Column(db.Unicode, unique=True)
    vendor = db.Column(db.Unicode)
    owner_id = db.Column(db.Integer, db.ForeignKey(''))
    purchase_time = db.Column(db.DateTime)

Also suppose we have registered an API for these models at /api/person and /api/computer, respectively.


For all requests that would return a list of results, the top-level JSON object is a mapping from "objects" to the list. JSON lists are not sent as top-level objects for security reasons. For more information, see this.

Error messages

Most errors return :http:statuscode:`400`. A bad request, for example, will receive a response like this:

HTTP/1.1 400 Bad Request

{"message": "Unable to decode data"}

Function evaluation

If the allow_functions keyword argument is set to True when creating an API for a model using :meth:`APIManager.create_api`, then an endpoint will be made available for :http:get:`/api/eval/person` which responds to requests for evaluation of functions on all instances the model.

Sample request:

GET /api/eval/person?q={"functions": [{"name": "sum", "field": "age"}, {"name": "avg", "field": "height"}]} HTTP/1.1

The format of the response is

HTTP/1.1 200 OK

{"sum__age": 100, "avg_height": 68}

If no functions are specified in the request, the response will contain the empty JSON object, {}.


The functions whose names are given in the request will be evaluated using SQLAlchemy's func object.


To get the total number of rows in the query (that is, the number of instances of the requested model), use count as the name of the function to evaluate, and id for the field on which to evaluate it:


GET /api/eval/person?q={"functions": [{"name": "count", "field": "id"}]} HTTP/1.1


HTTP/1.1 200 OK

{"count__id": 5}


Responses to :http:method:`get` requests are paginated by default, with at most ten objects per page. To request a specific page, add a page=N query parameter to the request URL, where N is a positive integer (the first page is page one). If no page query parameter is specified, the first page will be returned. If page is specified but pagination has been disabled, this parameter will be ignored.

In addition to the "objects" list, the response JSON object will have a "page" key whose value is the current page. For example, a request to :http:get:`/api/person?page=2` will result in the following response:

HTTP/1.1 200 OK

  "page": 2,
  "objects": [{"id": 1, "name": "Jeffrey", "age": 24}, ...]

If pagination is disabled (by setting results_per_page=None in :meth:`APIManager.create_api`, for example), any page key in the query parameters will be ignored, and the response JSON will include a "page" key which always has the value 1.


As specified in in :ref:`queryformat`, clients can receive responses with limit (a maximum number of objects in the response) and offset (the number of initial objects to skip in the response) applied. It is possible, though not recommended, to use pagination in addition to limit and offset. For simple clients, pagination should be fine.

Jump to Line
Something went wrong with that request. Please try again.