.. WARNING:: This is the documentation for the REST interface. Unfortunately it is outdated and parts of the interface may not work anymore. REST Resources ============== ``/instance`` - Group/Organization Instances -------------------------------------------- index ***** * List all existing and non-hidden instances. * URL: ``http://[instance].adhocracy.cc/instance[.format]`` * Method: ``GET`` * Formats: ``html, json`` * Authentication: no * Pager prefix: ``instances_`` create ****** * Create a new instance for a group or organization. * URL: ``http://[instance].adhocracy.cc/instance[.format]`` * Method: ``POST`` * Formats: ``html, json`` * Authentication: yes * Parameters: * ``key``: A unique identifier for the instance. Short lower-case alpha-numeric text. This cannot be edited after the instance creation. * ``label``: A title for the instance. * ``description``: Short description for the instance, e.g. a mission statement. show **** * View an instance's home page or base data * URL: ``http://[instance].adhocracy.cc/instance/[key][.format]`` * Method: ``GET`` * Formats: ``html, json`` * Authentication: no * *Note*: If no instance subdomain has been specified, this will 302 to the actual instance. update ****** * Update some of an instance's properties. * URL: ``http://[instance].adhocracy.cc/instance/[key][.format]`` * Method: ``PUT`` * Formats: ``html, json`` * Authentication: yes * Parameters: * ``label``: A title for the instance. * ``description``: Short description for the instance, e.g. a mission statement. * ``required_majority``: The percentage of voters required for the adoption of a proposal (e.g. 0.66 for 66%). * ``activation_delay``: Delay (in days) that a proposal needs to maintain a majority to be adopted. * ``allow_adopt``: Whether to allow adoption polls on proposals (``bool``). * ``allow_delegate``: Whether to enable delegated voting (``bool``). * ``allow_index``: Allow search engine indexing (via robots.txt, ``bool``). * ``hidden``: Show instance in listings. * ``default_group``: Default group for newly joined members (one of: ``observer``, ``advisor``, ``voter``, ``supervisor``). delete ****** * Delete an instance and all contained entities. * URL: ``http://[instance].adhocracy.cc/instance/[key][.format]`` * Method: ``DELETE`` * Formats: ``html, json`` * Authentication: yes *(requires global admin rights)* * *Note*: This will also delete all contained items, such as proposals, delegations, polls or comments. activity ******** * Retrieve a list of the latest events relating to this instance. * URL: ``http://[instance].adhocracy.cc/instance/[key]/activity[.format]`` * Method: ``GET`` * Formats: ``html, rss`` * Authentication: no * Pager prefix: ``events_`` join **** * Make the authenticated user a member of this ``Instance``. * URL: ``http://[instance].adhocracy.cc/instance/[key]/join[.format]`` * Method: ``GET`` * Formats: ``html`` * Authentication: yes * *Note*: Fails if the user is already a member of the instance. leave ***** * Terminate the authenticated user's membership in this ``Instance``. * URL: ``http://[instance].adhocracy.cc/instance/[key]/leave[.format]`` * Method: ``POST`` * Formats: ``html`` * Authentication: yes * *Note*: Fails if the user is not a member of the instance. ``/user`` - User Management --------------------------- index ***** * List all users with an active membership in the specified instance. * URL: ``http://[instance].adhocracy.cc/user[.format]`` * Method: ``GET`` * Formats: ``html, json`` * Authentication: no * Pager prefix: ``users_`` * Parameters: * ``users_q``: A search query to filter with. * ``users_filter``: Filter by membership group (only in an instance context). * *Note*: If no instance is specified, all registered users will be returned. create ****** * Create a new user. * URL: ``http://[instance].adhocracy.cc/user[.format]`` * Method: ``POST`` * Formats: ``html, json`` * Authentication: no * Parameters: * ``user_name``: A unique user name for the new user. * ``email``: An email, must be validated. * ``password``: A password, min. 3 characters. * ``password_confirm``: Must be identical to ``password``. * *Note*: Does not require an instance to be specified. If an instance is selected, the user will also become a member of that instance. show **** * View an user's home page and activity stream, * URL: ``http://[instance].adhocracy.cc/user/[user_name][.format]`` * Method: ``GET`` * Formats: ``html, json, rss`` * Authentication: no * *Note*: Also available outside of instance contexts. update ****** * Update the user's profile and settings. * URL: ``http://[instance].adhocracy.cc/user/[user_name][.format]`` * Method: ``PUT`` * Formats: ``html, json`` * Authentication: yes *(either to own user or with user management permissions)* * Parameters: * ``display_name``: Display name, i.e. the real name to be shown in the application. * ``email``: E-Mail address. Must be re-validated when changed. * ``locale``: A locale, currently: ``de_DE``, ``en_US`` or ``fr_FR``. * ``password``: A password, min. 3 characters. * ``password_confirm``: Must be identical to ``password``. * ``bio``: A short bio, markdown-formatted. * ``email_priority``: Minimum priority level for E-Mail notifications to be sent (0-6). * ``twitter_priority``: Minimum priority level for Twitter direct message notifications to be sent (0-6). delete ****** * Delete an user. **Not implemented** votes ***** * Retrieve a list of the decisions that were made by this user. * URL: ``http://[instance].adhocracy.cc/user/[user_name]/votes[.format]`` * Method: ``GET`` * Formats: ``html, json`` * Authentication: no * Pager prefix: ``decisions_`` * *Note*: Does not include rating polls, limited to adoption polls. delegations *********** * Retrieve a list of the delegations that were created by this user. * URL: ``http://[instance].adhocracy.cc/user/[user_name]/delegations[.format]`` * Method: ``GET`` * Formats: ``html, json`` * Authentication: no * Pager prefix: ``delegations_`` *(``json`` view only)* * *Note*: In ``html``, lists both incoming and outgoing delegations. When rendered as ``json``, this only includes outgoing delegations. instances ********* * A list of all non-hidden instances in which the user is a member. * URL: ``http://[instance].adhocracy.cc/user/[user_name]/instances[.format]`` * Method: ``GET`` * Formats: ``html, json`` * Authentication: no * Pager prefix: ``instances_`` proposals ********* * A list of all proposals that the user has introduced. * URL: ``http://[instance].adhocracy.cc/user/[user_name]/proposals[.format]`` * Method: ``GET`` * Formats: ``html, json`` * Authentication: no * Pager prefix: ``proposals_`` groupmod ******** * Modify a user's membership in the current instance * URL: ``http://[instance].adhocracy.cc/user/[user_name]/proposals[.format]`` * Method: ``GET`` * Formats: ``html`` * Authentication: yes *(requires instance admin privileges)* * Parameters: * ``to_group``: Target group (one of: ``observer``, ``advisor``, ``voter``, ``supervisor``). kick **** * Terminate a user's membership in the current instance * URL: ``http://[instance].adhocracy.cc/user/[user_name]/proposals[.format]`` * Method: ``GET`` * Formats: ``html`` * Authentication: yes *(requires instance admin privileges)* * *Note*: Since the user can re-join at any time, this is largely a symbolic action. ``/proposal`` - Proposal drafting --------------------------------- index ***** * List all existing proposals in the given instance. * URL: ``http://[instance].adhocracy.cc/proposal[.format]`` * Method: ``GET`` * Formats: ``html, json`` * Authentication: no * Pager prefix: ``proposals_`` * Parameters: * ``proposals_q``: A search query to filter with. * ``proposals_state``: Filter by state (one of: ``draft``, ``polling``, ``adopted``). Only available if adoption polling is enabled in the selected instance. create ****** * Create a new proposal. * URL: ``http://[instance].adhocracy.cc/proposal[.format]`` * Method: ``POST`` * Formats: ``html, json`` * Authentication: yes * Parameters: * ``label``: A title for the proposal. * ``text``: Goals of the proposal. * ``tags``: Comma-separated or space-separated tag list to be applied to the proposal. * ``alternative`` (multiple values): IDs of any proposals that should be marked as an alternative to this proposal. show **** * View an proposals's goal page * URL: ``http://[instance].adhocracy.cc/proposal/[id][.format]`` * Method: ``GET`` * Formats: ``html, json`` * Authentication: no update ****** * Update some of a proposal's properties. * URL: ``http://[instance].adhocracy.cc/proposal/[id][.format]`` * Method: ``PUT`` * Formats: ``html, json`` * Authentication: yes * Parameters: * ``label``: A title for the proposal. * ``alternative`` (multiple values): IDs of any proposals that should be marked as an alternative to this proposal. * *Note*: The goal description and tag list are edited separately. delete ****** * Delete a proposal and any contained entities. * URL: ``http://[instance].adhocracy.cc/proposal/[id][.format]`` * Method: ``DELETE`` * Formats: ``html, json`` * Authentication: yes *(requires instance admin rights)* * *Note*: This will also delete all contained items, such as comments and delegations. delegations *********** * Retrieve a list of the delegations that exist regarding this proposal. * URL: ``http://[instance].adhocracy.cc/proposal/[id]/delegations[.format]`` * Method: ``GET`` * Formats: ``html, json`` * Authentication: no * Pager prefix: ``delegations_`` canonicals ********** * Retrieve a list of canonical comments regarding the proposal. Canonical comments are listed as "provisions" in the UI. * URL: ``http://[instance].adhocracy.cc/proposal/[id]/delegations[.format]`` * Method: ``GET`` * Formats: ``html, json`` * Authentication: no * *Note*: No pager. alternatives ************ * Retrieve a list of the alternatives that exist regarding this proposal. * URL: ``http://[instance].adhocracy.cc/proposal/[id]/alternatives[.format]`` * Method: ``GET`` * Formats: ``html, json`` * Authentication: no * Pager prefix: ``proposals_`` activity ******** * Retrieve a list of events within the scope of the given proposal. * URL: ``http://[instance].adhocracy.cc/proposal/[id]/activity[.format]`` * Method: ``GET`` * Formats: ``html, rss`` * Authentication: no * Pager prefix: ``events_`` adopt ***** * Trigger an adoption poll regarding this proposal. * URL: ``http://[instance].adhocracy.cc/proposal/[id]/adopt[.format]`` * Method: ``POST`` * Formats: ``html`` * Authentication: yes * *Note*: Requires at least one canonical comment. Adoption polls must be enabled on the instance level. tag *** * Apply an additional tag to a proposal (or support an existing tag). * URL: ``http://[instance].adhocracy.cc/proposal/[id]/tag[.format]`` * Method: ``GET`` * Formats: ``html`` * Authentication: yes * Parameters: * ``text``: Comma-separated or space-separated tag list to be applied to the proposal. untag ***** * Remove a tag association (tagging) from a proposal. * URL: ``http://[instance].adhocracy.cc/proposal/[id]/untag[.format]`` * Method: ``GET`` * Formats: ``html`` * Authentication: yes * Parameters: * ``tagging``: ID of the tagging association to be removed. * *Note*: Only taggings created by the user can be removed. ``/poll`` - Poll data and voting -------------------------------- show **** * View a poll, listing the current decisions and offering a chance to vote. * URL: ``http://[instance].adhocracy.cc/poll/[id][.format]`` * Method: ``GET`` * Formats: ``html, json`` * Authentication: no delete ****** * End a poll and close voting. * URL: ``http://[instance].adhocracy.cc/poll/[id][.format]`` * Method: ``DELETE`` * Formats: ``html, json`` * Authentication: yes * *Note*: This will only work for adoption polls, rating polls cannot be terminated. votes ***** * Retrieve a list of the decisions that were made regarding this poll. * URL: ``http://[instance].adhocracy.cc/poll/[id]/votes[.format]`` * Method: ``GET`` * Formats: ``html, json`` * Authentication: no * Pager prefix: ``decisions_`` * Parameters: * ``result``: Filter for a specific decision, i.e. -1 (No), 1 (Yes), 0 (Abstained). rate **** * Vote in the poll via rating. * URL: ``http://[instance].adhocracy.cc/poll/[id]/rate[.format]`` * Method: ``POST`` * Formats: ``html, json`` * Authentication: yes * *Note*: This implements relative voting, i.e. if a user has previously voted -1 and now votes 1, the result will be 0 (a relative change). Used for comment up-/downvoting. Unlike ``vote``, this will also trigger an automated tallying of the poll. It is thus slower, especially for large polls. vote ***** * Vote in the poll. * URL: ``http://[instance].adhocracy.cc/poll/[id]/vote[.format]`` * Method: ``POST`` * Formats: ``html, json`` * Authentication: yes * *Note*: This does not trigger tallying. Thus a subsequent call to ``show`` might yield an incorrect tally until a server background job has run. ``/comment`` - Commenting and comment history --------------------------------------------- index ***** * List all existing comments. * URL: ``http://[instance].adhocracy.cc/comment[.format]`` * Method: ``GET`` * Formats: ``json`` * Authentication: no * Pager prefix: ``comments_`` create ****** * Create a new comment within a specified context. * URL: ``http://[instance].adhocracy.cc/comment[.format]`` * Method: ``POST`` * Formats: ``html, json`` * Authentication: yes * Parameters: * ``topic``: ID of the Delegateable to which this comment is associated. * ``reply``: A parent comment ID, if applicable. * ``canonical`` (bool): Specify whether this is part of the implementation description of the proposal to which it will be associated. * ``text``: The comment text, markdown-formatted. * ``sentiment``: General tendency of the comment, i.e. -1 for negative, 0 for neutral and 1 for a supporting argument. show **** * View a comment separated out of their context. * URL: ``http://[instance].adhocracy.cc/comment/[id][.format]`` * Method: ``GET`` * Formats: ``html, json`` * Authentication: no update ****** * Create a new revision of the given comment. * URL: ``http://[instance].adhocracy.cc/comment/[id][.format]`` * Method: ``PUT`` * Formats: ``html, json`` * Authentication: yes * Parameters: * ``text``: The comment text, markdown-formatted. * ``sentiment``: General tendency of the comment, i.e. -1 for negative, 0 for neutral and 1 for a supporting argument. delete ****** * Delete a comment. * URL: ``http://[instance].adhocracy.cc/comment/[id][.format]`` * Method: ``DELETE`` * Formats: ``html, json`` * Authentication: yes * *Note*: Comments can only be deleted by non-admins if they have not yet been edited. history ******* * List all revisions of the specified comment. * URL: ``http://[instance].adhocracy.cc/comment/[id]/history[.format]`` * Method: ``GET`` * Formats: ``html, json`` * Authentication: yes * Pager prefix: ``revisions_`` revert ****** * Revert to an earlier revision of the specified comment. * URL: ``http://[instance].adhocracy.cc/comment/[id]/revert[.format]`` * Method: ``GET`` * Formats: ``html, json`` * Authentication: yes * Parameters: * ``to``: Revision ID to revert to. * *Note*: This will actually create a new revision containing the specified revision's text. ``/delegation`` - Vote delegation management -------------------------------------------- index ***** * List all existing delegations (instance-wide). * URL: ``http://[instance].adhocracy.cc/delegation[.format]`` * Method: ``GET`` * Formats: ``json, dot`` * Authentication: no * Pager prefix: ``delegations_`` * *Note*: The ``dot`` format produces a graphviz file. create ****** * Create a new delegation to a specified principal in a given scope. * URL: ``http://[instance].adhocracy.cc/delegation[.format]`` * Method: ``POST`` * Formats: ``html, json`` * Authentication: yes * Parameters: * ``scope``: ID of the ``Delegateable`` which will be the delegation's scope. * ``agent``: User name of the delegation recipient. * ``replay``: Whether or not to re-play all of the agents previous decisions within the scope. show **** * View the delegation. * URL: ``http://[instance].adhocracy.cc/delegation/[id][.format]`` * Method: ``GET`` * Formats: ``html, json`` * Authentication: no * Pager prefix: ``decisions_`` * *Note*: For ``json`` this will return a tuple of the actual serialized delegation and a list of decisions. delete ****** * Revoke a the delegation. * URL: ``http://[instance].adhocracy.cc/delegation/[id][.format]`` * Method: ``DELETE`` * Formats: ``html, json`` * Authentication: yes * *Note*: Can only be performed by the delegation's principal.