Model Collection Resources

Model collection resources are configured for HTTP GET methods only to conform to common usage patterns.

• the default URL function returns a single URL, such as [/api/v1/items]. Note that it is still wrapped in a list for consistency for usage in

  api.add_resource(MyCollection, *MyCollection.get_urls())

• serialization / deserialization services operate in the same fashion as the ModelResource class.

• process_get_input is the same except that kwargs are not used.

• Additional class variables are used to assist in returning lists.

• the parser for the query_string looks for additional variables to provide guidance for the database queries such as sorting, filtering, paging.

Class Variables

As discussed in Model Resources class variables are used here as well.

• url_prefix

• url_name

• serial_fields

• serial_field_relations

• process_get_input

Additional Variable Defaults

• max_page_size = None

• order_by = None

max_page_size can be used automatically limit the number of entries in a list for paging to avoid outputting too much in one query.

Input Processing

The following parameters and returns should be used for process_get_input. Like the model resource, the function must return a dictionary in the format of:

{"status" True, "query": query, "data": data}
{"status": False, "message": message, "status_code": status_code}

A status of True enables normal processing, but with some tweaking of the data or query for this particular resource.

A status of False diverts normal processing to abort the process or send it in another direction.

Queries

The GET method looks to the request.query_string for filtering the resource, using a dict of column names as keys and specific values for which to select.

The standard format for the query string:

query_string = {"var1": val1}

Select multiple values from the same variable:

query_string = {"var2[]": [val1, val2, val3, ...]}

Comparison operators for a single value can also be used:

query_string = {"var3": [operator, val1 ]}

The operator must be found in [“eq”, “ne”, “gt”, “ge”, “lt”, “le”, “like”, “ilike”, “notlike”, “notilike”].

Variables can also be filtered by comparing to other variables. Putting a prefix of var: alerts the selection to use a column name.

query_string = {"var5": ["gt", "var:var6"]}

Within the query string there can also be other variables. To avoid cluttering up column name space, these variables are behind the keyword, page_config.

query_string = {
    "var1": val1,
    "page_config": {
        "order_by": var1
    }
}

• page_size: This limits the number entries that are output.If the page size is greater than a class resource variable, max_page_size, then the max_page_size will be used instead.

• offset: This is the number of entries to skip before outputting lines

• order_by: This is the order of the list and multiple variables can be used.

Examples:

"order_by": "var1"      ascending
"order_by": "-var1"     descending

"order_by": ["var1", "var2"]

• serial_fields: Control of the fields returned can controlled by query. This enables a query to limit the number of fields by query. The default fields derive from the underlying DBBase model. Within the model the fields can be specified. Also, the resource model can also define what fields are returned. So, multiple levels of detail can be returned, depending upon the application.

• debug: If True, it will return the SQL query and other information instead of executing the query to help assess if it is formulated correctly.

Note that the parameter variables can enter as camel case and will be converted along with the column names and variables.

Processing the Query

Once the query has been processed, the serial fields and relational fields will be applied to create the output. The form of the output is:

{"MyModel": [
    {"id": 1, "field1": value1, "field2": value2, ...},
    {"id": 2, "field1": value1, "field2": value2, ...},
    {"id": 3, "field1": value1, "field2": value2, ...},
    {"id": 4, "field1": value1, "field2": value2, ...}
]}

Next: Meta Resources