{% extends "layout.html" %}
{% block title %}reference{% endblock %}
{% block head %}
{% endblock %}
{% block body %}
To allow integration with other web applications and services,
statscache offers a simple, easy-to-use REST API with support for
multiple convenient data formats.
The API is accessible under the
The list of available models is accessible via at
Certain models are associated with a layout attribute
that describes the structure of the model. If a given model
The rows of any model overview
queries
{{ url_for('plugin_index') }}
tree. As this interface is meant to export data, only
GET
requests are supported on all endpoints.
index
{{ url_for('plugin_index') }}
. The identifiers are
composed of ASCII characters excluding spaces, single or double
quotes, punctuation, parantheses, ampersands, and asterisks.
layout
model
has a layout attribute, it is accessible
at {{ url_for('plugin_layout', ident='model') }}
.
feed
model
that was listed by the
index may be retrieved at the
{{ url_for('plugin_model', ident='model') }}
endpoint. Because a literal dump of the database table would be
ridicoulously inefficient, the results of any query are
paginated using the protocol discussed later. Queries may be
customized using the following query string parameters:
order
:
desc
or asc
to descend
(default) or ascend by row timestamp, respectively.
limit
:
a natural number (integer greater than or equal to
zero) to restrict the number of rows in the result to
at most that many, prior to pagination.
rows_per_page
:
an integer in the interval [0, 100] (defaulting to 100)
which will be the number of rows returned in each page.
page
:
a number n greater than zero (defaulting to 1)
to request the nth page of rows, which are the
rows_per_page
rows after skipping the
initial (n-1)×rows_per_page
rows.
start
:
an integer or floating-point number that is interpreted
as the second-based UNIX timestamp before which rows
are filtered out.
stop
:
an integer or floating-point number that is interpreted
as the second-based UNIX timestamp after which rows
are filtered out.
With the exception of layouts, all endpoints support serialization
to JSON[-P] and CSV. The HTTP Accept
header is what
determines the format of the response. Both the text/
or application/
prefixes are accepted. Note that a
request for JavaScript content is interpreted exactly the same as
a request for JSON data, and in either case a JSON-P request will
get a response with a JavaScript mime-type.
The statscache web API supports Cross-Origin Resource Sharing (CORS), an opt-in mechanism to allow direct AJAX requests and access to designated response headers. Using CORS requires no additional work on your part, as most major JavaScript libraries transparently activate it when appropriate.
Cross-origin AJAX requests may also be done the traditional way, using JSON-P, but that method is neither necessary not recommended. JSON-P is limited in that there is no way to retrieve the response headers, which statscache uses to pass on important metadata regarding pagination. Still, if you are in a situation where there are compelling reasons to do so, using JSON-P is an option.
In feed responses, statscache passes on information about
pagination through several headers. (If you're familiar with the
GitHub API, this mechanism is very similar.) The Link
header is used to provide links to the next
and
previous
pages, if they exist. Every response also includes
an X-Link-Number
and an X-Link-Count
header, which give the current page number (starting from one) and
the total number of pages, respectively.