Traversal API

Routes begin with /data/ and correspond to assembl.views.api2. These routes are automatically generated from the classes which are defined, and their properties can be traversed. The first element after /data/ is the external name (cf assembl.lib.sqla.BaseOps.external_typename()) of a Python class for which we want to list the instances, or to access a specific instance. It can be followed by the database id of an instance of this class (for example: /data/Discussion/6 ). Some classes (Discussion, Preferences) also have unique names which can be used in traversal: /data/Discussion/slug ).

View defs

An API call can contain a parameter “view” (for example: /data/Discussion/?view=partial ). Its value is the name of a view def. View defs are JSON files which are defined in assembl.view_def. A view def defines for each class the properties which the server is allowed to send back to the client, or which are allowed to be modified by a POST/PUT API call.

Collections

The API URL of an object instance can be followed by /@@collections . This will list all collections available from this instance. A collection of this list can be one of:

  • a relation (in the ORM sense: OneToMany or ManyToOne)
  • the backref of a relation (this is an inverse relation, which has been defined in the other class of the relation, not in this one)
  • a collection which has been defined via extra\_collections. In this case, the JOIN operation has been coded manually. (assembl.views.traversal.CollectionDefinition.decorate_query(), assembl.views.traversal.CollectionDefinition.decorate_instance(), assembl.views.traversal.CollectionDefinition.contains()).

Notifications

Uses the generic API.

Get user notifications

All notifications, for this user, this discussion: /data/Discussion/6/all\_users/2/notification

A specific notification: /data/Discussion/6/all\_users/2/notification/1

Specific formats, append:

  • /mail: Raw email
  • /mail\_html\_preview: Preview the html part of the notification mail (if any)
  • /mail\_text\_preview: Preview the plain text part of the notification mail (if any)

Actions

Those actions are based on pyramid named views. (not strictly REST, but useful for debugging)

/process\_now: Notify the celery_notify celery task to try processing the notification immediately A global equivalent exists for all notifications: /data/Notification/process\_now

Examples

Get all posts for a discussion:
/api/v1/discussion/1/posts You can append a view, such as ?view=id\_only
Delete a message (Superadmin):
DELETE /data/Content/3244
Permission lookups:
GET /api/v1/discussion/2/permissions/add\_extract/u/
Frontend notes: Specific messages are adressed with urls such as
/jacklayton/posts/local%3AContent%2F16
Metrics and statistics (work in progress, api under flux): Ex:
/data/Discussion/11/time\_series\_analytics?interval=P1M&start=2014-01-01
Discussion preferences:
Raw data: (does not include permission cascade, use it to edit) /data/Discussion/1/preferences
Discussion preferences:
Cooked data (includes permission cascade) /data/Discussion/1/settings(/{key}) (In frontend: models/discussionPreference.js)
User Namespaced KV store:
/data/Discussion/1/user\_ns\_kv/{namespace}(/{key}) in particular /data/Discussion/1/user\_ns\_kv/preferences(/{key}) which contains the overrides found in user-corrected preference data: /data/Discussion/1/all\_users/current/preferences(/{key}) (In frontend: Ctx.getPreferences, which is taken from a tag.)