# 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()).

Uses the generic API.

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 /data/Content/3244
GET /api/v1/discussion/2/permissions/add\_extract/u/
/jacklayton/posts/local%3AContent%2F16
/data/Discussion/11/time\_series\_analytics?interval=P1M&start=2014-01-01
Raw data: (does not include permission cascade, use it to edit) /data/Discussion/1/preferences
Cooked data (includes permission cascade) /data/Discussion/1/settings(/{key}) (In frontend: models/discussionPreference.js)
/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.)