Function evaluation

This section describes behavior that is not part of the JSON API specification.

If the allow_functions keyword argument to APIManager.create_api() is set to True when creating an API for a model, then the endpoint /api/eval/person will be made available for GET requests. This endpoint responds to requests for evaluation of SQL functions on all instances the model.

If the client specifies the functions query parameter, it must be a percent-encoded list of function objects, as described below.

A function object is a JSON object. A function object must be of the form

{"name": <function_name>, "field": <field_name>}

where <function_name> is the name of a SQL function as provided by SQLAlchemy’s func object.

For example, to get the average age of all people in the database,

GET /api/eval/person?functions=[{"name":"avg","field":"age"}] HTTP/1.1
Host: example.com
Accept: application/json

The response will be a JSON object with a single element, data, containing a list of the results of all the function evaluations requested by the client, in the same order as in the functions query parameter. For example, to get the sum and the average ages of all people in the database, the request

GET /api/eval/person?functions=[{"name":"avg","field":"age"},{"name":"sum","field":"age"}] HTTP/1.1
Host: example.com
Accept: application/json

yields the response

HTTP/1.1 200 OK
Content-Type: application/json

[15.0, 60.0]

Example

To get the total number of resources in the collection (that is, the number of instances of the model), you can use the function object

{"name": "count", "field": "id"}

Then the request

GET /api/eval/person?functions=[{"name":"count","field":"id"}] HTTP/1.1
Host: example.com
Accept: application/json

yields the response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [42]
}

The function evaluation endpoint also respects filtering query parameters. Specifically, filters are applied to the model before the function evaluation is performed, so you can apply a function to a subset of resources. See Filtering for more information.

Changed in version 1.0.0b2: Adds ability to use filters in function evaluation.