API Documentation¶

Public API¶

The public API is exposed as a RESTful JSON interface using cornice and consists of the following services.

Note

For frontend developers, this is the only API documentation you should need.

Login¶

Existing users can log in using a PUT request at /login:

>>> browser.put_json('http://example.com/-/login', {
...   "login": "alice@foo.com",
...   "password": "alice"
... }).json['status']
u'success'

While logged in the frontend may request authentication info via GET:

>>> info = browser.get_json('http://example.com/-/login').json
>>> info['authenticated']
True
>>> info['firstname'], info['lastname'], info['email']
(u'Alice', u'Kingsleigh', u'alice@foo.com')

Logging out again is handled via a PUT at /logout:

>>> browser.put_json('http://example.com/-/logout', {}).json['status']
u'success'

Password reset¶

Existing users can request a password reset by POSTing to /reset/:

>>> browser.post_json('http://example.com/-/reset/', {
...   "email": "alice@foo.com"
... }).json['status']
u'success'

Password change¶

Existing users can change their password by PUTing to /password:

>>> browser.put_json('http://example.com/-/password', {
...   "current": "alice",
...   "password": "foo!"
... }).json['status']
u'success'

Email change¶

Existing users can request to change their email address by PUTing to /-/email/:

>>> browser.put_json('http://example.com/-/email/', {
...   "email": "alice@bar.com",
...   "password": "alice"
... }).json['status']
u'success'

User profile¶

Users can change their profile data by PUTing to /userprofile:

>>> data = browser.get_json('http://example.com/-/userprofile').json
>>> data['firstname']
u'Alice'
>>> data['lastname']
u'Kingsleigh'

>>> browser.put_json('http://example.com/-/userprofile', {
...   "firstname": "Alien",
...   "lastname": "Species",
... }).json['status']
u'success'

Base API Classes¶

The above JSON services are based on a few helper classes.

backrest.views.id_factory(model)¶: Returns a factory for the given model, which in turn will return the instance of that model with the id taken from the request’s matchdict. If no item with the id in question exists, NotFound is raised.

class backrest.views.Content(context, request)¶

A REST resource collection for content objects.

Every GET returns a JSON representation of the given resource, designed to be passed back into a PUT or POST call.

Every POST or PUT returns a (possibly updated) representation of the object that has been modified back to the calling client.

A client that wishes to perform an update should always post back the smallest subtree possible.

Technically, we use pyramid’s JSON renderer to generate the response, so in the service methods we simply return instances of our models, which in turn have a __json__ method, which is called by the renderer.

When posting or putting a resource we call its update method passing in the data. That method is expected to only process the keys that the model provides and to silently ignore any that are not. This behavior can be used to pass (read-only) meta data to the client, which by convention lives in a singly entry with a key named __meta__.

Ideally the client would never post data that contains this key, but even if so, it will be ignored.

Base Models¶

The below models try to provide a basis for content-like and file-like types. The latter deal with binary data using repoze.filesafe in order to be transaction-safe.