Molly as an API¶
Molly’s approach to views lends itself to a large amount of flexibility. One
such flexibility is the ability to vary the format of the rendered view based on
the Accept headers of the client, or a manual override of the data format based
on an additional GET parameter: format
.
To disable this functionality on a particular view (e.g., if the context contains
data that should not be exposed), you can set exposes_user_data
to True in
the context thus implying that the data is private and should not be exposed in the API.
The data formats supported are:
- XML
- JSON/JSONP
- YAML
And in each of these, a serialised form of the context is presented.
The JSON API also provides a field called view_name
which can be used to
uniquely identify the format of the response. This is discussed further below.
An additional format, ‘fragment’ is also available. This provides the body and title HTML of a template encoded using JSON. It’s used for the AJAX functionality introduced in Molly 1.1.
Adding serialisation to your apps¶
Molly will attempt to serialise many standard Python and Django objects, however
in some cases, this is too simplistic for many uses. Classes can therefore define
a simplify_for_render
method which can be used to manually specify how the
object can be simplified.
View names and page names¶
A view name is a unique identifier for the page which rendered the view. It
should uniquely identify the format of the response. It is in the format of
application:view_id
. The details of what are available for each view
Page names uniquely identify a particular instance of a page. Molly can handle multiple instantiations of an app, so this refers to the specific instance of the app. This is best illustrated with an example.
Let’s assume that we have two different phonebooks, one for people and another for departments. We may want to instantiate this as two different instances of the contact search app with the configuration below:
Application('molly.apps.contact', 'people', 'People search',
provider = 'example.providers.contact.PeopleSearchProvider',
),
Application('molly.apps.contact', 'departments', 'Department Phonebook',
provider = 'example.providers.contact.DepartmentSearch',
),
The page at http://example.com/people/ will therefore have a page name of
people:index
and the page at http://example.com/contact/ will have a page
name of departments:index
, however both pages when rendered will be
rendered by the view in the Molly app contact
so will have a view name of
contact:index
.
Page names are therefore used in breadcrumbs and on the home page apps listing as these refer to particular instances of apps, and these should be passed to the reverse API in order to get the URL of those particular instances. View name only exists as a convenience to help API users determine how to handle the response.
The reverse API¶
Django includes functionality to “reverse” a URL, that is, take a page or view
name and arguments to it and then return the URL on that Molly instance. This
endpoint exists at the /reverse/
URL at the highest level of the instance
(e.g., http://example.com/reverse/
) and takes two arguments: name
and
arg
, which can be specified multiple times. These correspond to the Django
URL resolver definition in the app’s urls.py
.
This page returns a simple string containing the URL. It is recommended that you cache these somewhere to avoid lookups.
For example, to resolve the URL for Doncaster rail station, we can simply
call the URL http://example.com/reverse/?name=places:entity&arg=crs&arg=DON
which will return the fully qualified URL for that page.
This functionality allows for applications to be written against Molly as a generic API, rather than one tied to the (URL configuration) of a particular Molly instance.