LiquidFeedback API specification (WORKING DRAFT)
Overview of data structures
General information
The LiquidFeedback API specification describes a general interface to access an instance of LiquidFeedback Core.
LiquidFeedback API makes use of HTTP(s). Data is send and requested by the corresponding HTTP-GET, POST or DELETE requests as described in this document.
It is mandatory to use the correct HTTP method. However it is possible to override the request type by adding the parameter value pair http_method=POST to the request URI, in case you environment only allows GET requests.
Request parameters
Request parameters can either be submitted via the "query" part of the HTTP request URI (GET parameters), or be submitted as x-www-form-urlencoded data in the body of a POST request (POST parameters). For POST requests it is also possible to mix both ways; x-www-form-urlencoded values in the body have precendence in this case.
Encoding
Strings are URL encoded (percent encoded), as specified for URI's and x-www-form-urlencoded POST bodys. Integers are sent as ASCII encoded strings. Boolean values must be encoded as the letter one ('1') for true and as the letter zero ('0') for false. Note that submitting zero ('0') for false is not always the same as submitting no key at all.
Response
Requests being formally valid will be answered with a HTTP status of 200. The response body contains a JSON document with the following possible elements ("status" is mandatory, all other fields are optional):
{
status: 'ok',
error: '...',
result: [ { ... }, { ... }, ... ],
members: { 1: { ... }, 2: { ... }, ... },
suggestions: { 1: { ... }, 2: { ... }, ... },
initiatives: { 1: { ... }, 2: { ... }, ... },
issues: { 1: { ... }, 2: { ... }, ... },
areas: { 1: { ... }, 2: { ... }, ... },
units: { 1: { ... }, 2: { ... }, ... },
policies: { 1: { ... }, 2: { ... }, ... },
issue_id: 1,
initiative_id: 1,
draft_id: 1
}
Some special requests can return additional response fields on the root level. This is documented for each request where applicable.
elements
status string
A string indicating if the request could be executed.
ok Request was processed successfully.
forbidden Neccessary privileges are missing in order to proceed the request.
notfound The desired request is not available.
unprocessable The request contains invalid parameters or an invalid combination of parameters (i.e. semantic errors)
error An error occurred while processing your request (i.e. other server error).
error string
If an error occured (status not 'ok'), then a description of the error is returned in the "error" field of the JSON response.
result list
The objects, which have been requested, are returned in the "result" list. The type of its elements depends on the request.
additional lists of members, suggestions, initiatives, issues, areas, units and/or policies
Using include_* parameters, it is possible to fetch additional objects along with the main objects, which are requested. For more information see section Fetch related data in same request below.
issue_id, initiative_id, draft_id ===
These ids are included in the resulting object when creating a new draft.
Encoding of values in the JSON response
The data types known to JSON (strings, integer, boolean) are encoded as specified for JSON. Timestamps in reply are in UTC and encoded like '2009-08-07T12:34:56.789Z'// ( ISO 8601 time format). Intervals in reply are encoded like { weeks: 2 } or like { months: 1, days: 23 } ([ http://www.postgresql.org/docs/9.0/static/datatype-datetime.html#INTERVAL-STYLE-OUTPUT-TABLE ]).
Application authentication and session management
The authentication and session management is not yet specified. For testing purposes a preliminary very simple authentication interface is described as follows.
POST /session
Request a session key for a given application key. The session key has to be added to all subsequent requests as session_key parameter. Session can be terminated at any time, so applications have to be aware of that. (TODO: specify error code)
Request parameters:
key (string) Registered application key
Returns no "result" set, but following special element in root of JSON response:
session_key (string)
Security
It is highly recommended to make the service ONLY available via SSL! The application itself is not providing SSL itself, so please use a SSL proxy for that.
TODO!
Snapshots
The calculcation of delegation chains is time consuming. Because of that a snapshot of the current delegation chains for every issue is calculated periodically by a background job. At some points in time (i.e. issue state changes) the current snapshot is saved for future use. The current snapshot is referred to as "latest", the saved snapshots are called: "end_of_admission", "half_freeze" and "full_freeze". These references can be used for the GET methods "population", "interest" and "support".
Generic request parameters
For many requests one or all of the following generic request parameters can be used. The conditions under which a generic request parameter is available are described below.
Fetch related data in same request
To lower the number of API requests to get all data needed for a task, you can request to include data of related objects in the reply. These data will be included in the result object next to the result itself as shown in the response section above. The additional data is available as an associative array, where the id is used as key.
include_suggestions (boolean) If true, related suggestions will be included in the reply. Only applicable for objects having a suggestion_id attribute.
include_initiatives (boolean) If true, related initiatives will be included in the reply. Only applicable for objects having an initiative_id or if include_suggestions is set.
include_issues (boolean) If true, related issues will be included in the reply. Only applicable for objects having an issue_id or if include_initiatives is set.
include_areas (boolean) If true, related areas will be included in the reply. Only applicable for objects having an area_id or if include_issues is set.
include_units (boolean) If true, related units will be included in the reply. Only applicable for objects having an unit_id or if include_areas is set.
include_policies (boolean) If true, related policies will be included in the reply. Only applicable for objects having an issue_id or if include_issues is set.
Ordering
Depending on the request, result sets can be ordered by providing an "order" parameter to the request. The available options for this parameter are documented for each request where applicable.
Limit and offset
Available for any request that creates a result list.
limit (integer) Maximum numbers of results to return (default 101, maximum 1001)
offset (integer) Skips the given number of results
Member options
Available for requests where noted.
member_id (integer) Member id to lookup, separate multiple ids by comma
member_disabled (string) "include" includes disabled members, "only" selects only disabled members
member_search (string) Search term, separate multiple search terms by space (" ")
member_order_by_name (integer) Order result by member name
member_order_by_creation (integer) Order result descending by member creation timestamp
Policy options
Available for requests where noted.
policy_id (integer) Policy id to lookup, separate multiple ids by comma
policy_order_by_name (boolean) Order result by policy name
Unit options
Available for requests where noted.
unit_id (integer) Unit id to lookup, separate multiple ids by comma
unit_parent_id (integer) Lookup only units which are direct child of given parent unit
unit_without_parent (boolean) Lookup only units in root
unit_disabled (string) "include" includes disabled units, "only" selects only disabled units
unit_order_by_path (integer) Order result by unit path name
Area options
Available for requests where noted.
<unit options> (Where area options are available, unit options can be used as well)
area_id (int) Area id to lookup, separate multiple ids by comma
area_disabled (string) "include" includes disabled areas, "only" selects only disabled areas
Issue options
Available for requests where noted.
<area options> (Where issue options are available, area options can be used as well)
<policy options> (Where issue options are available, policy options can be used as well)
issue_id (int) Issue id to lookup, separate multiple ids by comma
issue_state (string) Current state of issue, separate multiple states by comma, omit for any
issue_created_after (timestamp) Select issues created after given timestamp
issue_created_before (timestamp) Select issues created before given timestamp
issue_accepted (boolean) Select accepted (true) or non-accepted (false) issues
issue_accepted_after (timestamp) Select issues accepted after given timestamp
issue_accepted_before (timestamp) Select issues accepted before given timestamp
issue_half_frozen (boolean) Select half-frozen (true) or non-half-frozen (false) issues
issue_half_frozen_after (timestamp) Select issues half-frozen after given timestamp
issue_half_frozen_before (timestamp) Select issues half-frozen before given timestamp
issue_fully_frozen (boolean) Select fully frozen (true) or not fully frozen (false) issues
issue_fully_frozen_after (timestamp) Select issues fully frozen after given timestamp
issue_fully_frozen_before (timestamp) Select issues fully frozen before given timestamp
issue_closed (boolean) Select closed (true) or open (false) issues
issue_closed_after (timestamp) Select issues closed after given timestamp
issue_closed_before (timestamp) Select issues closed before given timestamp
issue_ranks_available (boolean) Select issues for which ranks are available (true) or not available (false)
issue_cleaned (boolean) Select issues which are cleaned (true) or not cleaned (false)
issue_cleaned_after (timestamp) Select issues cleaned after timestamp
issue_cleaned_before (timestamp) Select issues cleaned before timestamp
issue_state_time_left_below (interval) Select issues which time left for current state is below given interval
Initiative options
Available for requests where noted.
<issue options> (Where initiative options are available, issue options can be used as well)
<member options prefixed with "initiator_"> (Where initiative options are available, member options can be used with "initiator_" prefix to refer to initiators of initiatives)
<member options prefixed with "supporter_"> (Where initiative options are available, member optiosn can be used with "supporter_" prefix to refer to supporters of initiatives)
initiative_id (int) Initiative id to lookup, separate multiple ids by comma
initiative_created_after (timestamp) Select initiatives created after given timestamp
initiative_created_before (timestamp) Select initiatives created before given timestamp
initiative_revoked (boolean) Select revoked (true) or non-revoked (false) initiatives
initiative_revoked_after (timestamp) Select initiatives revoked after given timestamp
initiative_revoked_before (timestamp) Select initiatives revoked before given timestamp
initiative_revoked_by_member_id (integer) Select initiatives revoked by the referenced member
initiative_admitted (boolean) Select admitted (true) or non-admitted (false) initiatives
initiative_admitted_after (timestamp) Select initiatives admitted after given timestamp
initiative_admitted_before (timestamp) Select initiatives admitted before given timestamp
initiative_suggested_initiative_id (integer) Select initiatives suggesting the referenced initiative
initiative_supporter_count_below (integer) Select initiatives with a supporter count below the given number
initiative_supporter_count_above (integer) Select initiatives with a supporter count above the given number
initiative_direct_majority (boolean) Select initiatives with (true) or without (false) a direct majority
initiative_indirect_majority (boolean) Select initiatives with (true) or without (false) an indirect majority
initiative_attainable (boolean) Select initiatives with a direct and indirect majority (true) or without either a direct or an indirect majority (false)
initiative_better_than_status_quo (boolean) Select initiatives with (true) or without (false) a better schulze-rank than the status-quo
initiative_worse_than_status_quo (boolean) Select initiatives with (true) or without (false) a worse schulze-rank than the status-quo
initiative_reverse_beat_path (boolean) Select initiatives where there is (true) or where there is no (false) beat-path (including ties) to the status-quo
initiative_multistage_majority (boolean) Select initiatives with (true) or without (false) mutistage_majority flag set
initiative_eligible (boolean) Select initiatives which have been (true) or have not been (false) eligible as winner in final voting
initiative_winner (boolean) Select initiatives which have (true) or have not (false) won in final voting
initiative_search (string)
Suggestion options
Available for requests where noted.
<initiative options> (Where suggestion options are available, initiative options can be used as well)
suggestion_id (int)
ENUMs
issue states
admission
discussion
verification
voting
canceled_revoked_before_accepted
canceled_issue_not_accepted
canceled_after_revocation_during_discussion
canceled_after_revocation_during_verification
calculation
canceled_no_initiative_admitted
finished_without_winner
finished_with_winner
open (pseudo state including all correspondent states)
closed (pseudo state including all correspondent states)
snapshot events (not to be confused with event types)
periodic
end_of_admission
half_freeze
full_freeze
latest (pseudo event referring to the latest event)
event types (not to be confused with snapshot events)
issue_state_changed
initiative_created_in_new_issue
initiative_created_in_existing_issue
initiative_revoked
new_draft_created
suggestion_created
delegation scopes
unit (organizational unit)
area (subject area)
issue (single issue)
General information
GET /info
[access levels: member, full, pseudonym, anonymous]
Get current version of core and api and access level of current connection. Clients should check API version after startup before doing any other request.
No request parameters
Returns no "result" set, but following special elements in root of JSON response:
core_version (string) Version number of the LiquidFeedback Core., i.e. 1.2.34
api_version (string) Version number of the LiquidFeedback API, i.e. 1.0.0
current_access_level (string) The access level of the current session, can be "none", "anonym", "pseudonym", "full", "member".
current_member_id (integer) The id of the currently logged in member, null if none
member_ttl (interval) Interval after a member without activity will be deactivated
settings (object) A nested structure of settings, taken from config.settings
GET /member_count
[access levels: member, full, pseudonym, anonymous]
No request parameters
Returns no "result" set, but following special elements in root of JSON response:
total_count (integer) Count of members currently having voting right
calculated (timestamp) Timestamp the core has calculated the returned member_count value
GET /contingent
[access levels: member, full, pseudonym, anonymous]
Get current write contingent configuration. Contingents are the amount of text entries or initiatives a user may create within a given time frame. Only one row needs to be fulfilled for a member to be allowed to post. This constraint is checked by the API Server.
Returns "result" set of:
contingent (object)
time_frame (interval)
text_entry_limit (int) Number of new drafts or suggestions to be submitted by each member within the given time frame
initiative_limit (int) Number of new initiatives to be opened by each member within a given time frame
GET /contingent_left
[access levels: member]
Returns no "result" set, but special element "contingent_left" in root of JSON response:
contingent_left (object)
time_frame (interval)
text_entry_limit (int) Number of new drafts or suggestions to be submitted by each member within the given time frame
initiative_limit (int) Number of new initiatives to be opened by each member within a given time frame
POST /echo_test
Only for testing purposes. Responds the data posted.
Request parameters:
<any> (any)
Result parameters in root of JSON response:
<any> (any)
Members
GET /member
[access levels: member, full, pseudonym]
Request information about a specific user or a set of specific users of the system. When called with access level "pseudonym" it will only return the fields id and name.
Request parameters:
render_statement (string) If set to html, statement will be returned rendered as html
Returns "result" set of:
member (object)
id (int) Primary key
activated (timestamp) Timestamp of first activation of account (i.e. usage of "invite_code")
last_activity (date) Date of last activity of member
last_login (timestamp) Timestamp of last login in main interface
locked (boolean) Locked members can not log in.
active (boolean) Memberships, support and votes are taken into account when corresponding members are marked as active. Automatically set to FALSE, if "last_activity" is older than "member_ttl"
admin (boolean) Indicates if member is administrator of the system
name (string) Distinct name of the member, may be changed freely
identification (string) Optional identification number or code of the member
organizational_unit (string) Branch or division of the organization the member belongs to
internal_posts (string) Posts (offices) of the member inside the organization
realname (string) Real name of the member, may be identical with "name"
birthday (date)
address (string)
email (string) Published email address of member; not used for system notifications
xmpp_address (string)
website (string)
phone (string)
mobile_phone (string)
profession (string)
external_memberships (string) Other organizations the member is involved in
external_posts (string) Posts (offices) outside the organization
formatting_engine (string) Formatting engine used for "statement"
statement (string) Freely chosen text of the member for his/her profile
POST /member
[access levels: member]
Update personal profile data of current member.
Request parameters:
organizational_unit (string)
internal_posts (string)
realname (string) (availability depends on configuration, TODO)
birthday (date)
address (string)
email (string)
xmpp_address (string)
website (string)
phone (string)
mobile_phone (string)
profession (string)
external_memberships (string)
external_posts (string)
formatting_engine (string)
statement (string)
GET /member_history
[access levels: member, full]
Request parameters:
Returns "result" set of:
member_history_entry (object)
id (integer) Primary key, which can be used to sort entries correctly (and time warp resistant)
member_id (timestamp)
until (timestamp) Timestamp until the described state had been valid
active (boolean) (see GET /member)
name (string) (see GET /member)
GET /member_image
[access levels: member, full]
Request parameters:
type (string) Type of image, can be "avatar" or "photo"
Returns "result" set of:
member_image (object)
member_id (int8)
image_type (string) Image type (avatar or photo)
content_type (string) Mime-type of the image, ie. image/jpeg
data (binary) The data itself, base64 encoded
POST /member_image
[access levels: member]
Update avatar or portrait image.
Request parameters:
image_type (string) Image type (avatar or portrait)
data (binary) Image data, encoded as ??? (TODO)
GET /contact
[access levels: member, full, pseudonym]
Request parameters:
Returns "result" set of:
contact (object)
member_id (integer) Member, who saved this contact
other_member_id (integer) Member, who is saved as contact
public (integer) Contact is published
POST /contact
[access levels: member]
Set or remove, publish and unpublish a contact.
Request parameters:
other_member_id (int) Id of the member to save as contact
public (boolean) True, if the contact should be published
delete (boolean) If true, delete contact
GET /privilege
[access levels: member, full, pseudonym]
Request parameters:
Returns "result" set of:
privilege (object)
unit_id (integer)
member_id (integer)
admin_manager (boolean) Member can grant/revoke admin privileges to/from other members
unit_manager (boolean) Member can create and disable sub units
area_manager (boolean) Member can create and disable areas and set area parameters
voting_right_manager (boolean) Member can select which members are allowed to discuss and vote within the unit
voting_right (boolean) Member has right to discuss and vote within the unit
Policies
GET /policy
Get informations about policies.
Request parameters:
Returns "result" set of:
policy (object)
id (integer) Primary key
active (boolean) True, if policy can be used for new issues
index (integer) Determines the order in listings
name (string) Name of policy
description (string) Description of policy
admission_time (interval) Maximum duration of issue state "admission"
discussion_time (interval) Duration of issue state "discussion"
verification_time (interval) Duration of issue state "verification"
voting_time (interval) Duration of issue state "voting"
issue_quorum_num (integer) Numerator of potential supporter quorum to be reached by one initiative of an issue to enter issue state "discussion"
issue_quorum_den (integer) Denominator of potential supporter quorum to be reached by one initiative of an issue to enter issue state "discussion"
initiative_quorum_num (integer) Numerator of satisfied supporter quorum to be reached by an initiative to be "admitted" for voting
initiative_quorum_den (integer) Denominator of satisfied supporter quorum to be reached by an initiative to be "admitted" for voting
direct_majority_num (integer) Numerator of fraction of neccessary direct majority for initiatives to be attainable as winner
direct_majority_den (integer) Denominator of fraction of neccessary direct majority for initaitives to be attainable as winner
direct_majority_strict (boolean) If true, then the direct majority must be strictly greater than direct_majority_num/direct_majority_den, otherwise it may also be equal
direct_majority_positive (integer) Absolute number of positive_votes neccessary for an initiative to be attainable as winner
direct_majority_non_negative (integer) Absolute number of sum of positive_votes and abstentions neccessary for an initiative to be attainable as winner
indirect_majority_num (integer) Numerator of fraction of neccessary indirect majority for initiatives to be attainable as winner
indirect_majority_den (integer) Denominator of fraction of neccessary indirect majority for initaitives to be attainable as winner
indirect_majority_strict (boolean) If true, then the indirect majority must be strictly greater than indirect_majority_num/indirect_majority_den, otherwise it may also be equal
indirect_majority_positive (integer) Absolute number of positive_votes neccessary for an initiative to be attainable as winner
indirect_majority_negative (integer) Absolute number of sum of positive_votes and abstentions neccessary for an initiative to be attainable as winner
no_reverse_beatpath (boolean) Causes initiatives with a beat-path to the status-quo (including ties) to not be "eligible" as winner
no_multistage_majority (boolean) Causes initiatives with "multistage_majority" flag set to not be "eligible" as winner
Units
GET /unit
Get information about units.
Request parameters:
Returns "result" set of:
unit (object)
id (integer) Primary key
parent_id (integer) Referencing the parent unit (unset/null if unit is in root level)
active (boolean) New issues can be created in areas of this unit
name (string) Name of the unit
description (string) Description of the unit
member_count (integer) Count of currently active members with voting right for this unit. Value is calculated periodically by the core.
Areas
GET /area
Request parameters:
Returns "result" set of:
area (object)
id (integer) Primary key
unit_id (integer) Unit to which the area belongs
active (boolean) New issues can be created in the area
name (string) Name of area
description (string) Description of area
direct_member_count (integer) Count of active members of that area (ignoring their weight)
member_weight (integer) Same as direct_member_count, but respecting delegations
GET /allowed_policy
Request parameters:
Returns "result" set of:
allowed_policy (object)
area_id (integer)
policy_id (integer)
default_policy (boolean) Policy should be given as default for the area
GET /membership
Request parameters:
Returns "result" set of:
membership (object)
area_id (integer)
member_id (integer)
POST /membership
[access levels: member]
Set or remove membership to/from area.
Request parameters:
area_id (integer) Id of area to become member of
delete (boolean) If true, remove membership
Issues
GET /issue
Request parameters:
Returns "result" set of:
issue (object)
id (integer) Primary key
area_id (integer) Area where issue has been created in
policy_id (integer) Policy which the issue uses
state (enum) Issue state, see ENUMs
created (timestamp) Time, when first initiative was created
accepted (timestamp) Time, when first quorum was passed
half_frozen (timestamp) Time, when discussion time ended
fully_frozen (timestamp) Time, when verification time ended
closed (timestamp) Time, when issue was closed (e.g. voting time ended, quorum failed, etc.)
ranks_available (boolean) True, if schulze-ranks have been calculated
cleaned (timestamp) Time, when voting data was deleted
admission_time (interval) Copied from policy on creation of issue
discussion_time (interval) Copied from policy on creation of issue
verification_time (interval) Copied from policy on creation of issue
voting_time (interval) Copied from policy on creation of issue
snapshot (interval) Time of last snapshot
latest_snapshot_event (enum) Reason of last snapshot, see ENUMs
population (integer) Weight of area members and interested members (used for quorums)
voter_count (integer) Weight of members voting (sum of direct and delegating voters)
status_quo_schulze_rank (integer) Schulze rank of status quo
GET /population
Request parameters:
snapshot (enum) Mandatory: Request population snapshot for the given event. Valid events are 'latest', 'end_of_admission', 'half_freeze', 'full_freeze' (see ENUMs). Separate multiple by comma.
Returns "result" set of:
population (object)
issue_id (integer)
event (enum) Snapshot event, see ENUMs
member_id (integer)
weight (integer) Voting weight of member due to delegations at point in time of given event
scope (enum) Scope of delegation of this member to the first member in delegate_member_ids (see ENUMs). Null for directly interested members or members of area.
delegate_member_ids (*integer) List of member ids in delegation chain. Null for directly interested members or members of area.
GET /interest
Request parameters:
snapshot (enum) Request interest snapshot for the given event. Valid events are 'latest', 'end_of_admission', 'half_freeze', 'full_freeze' (see ENUMs). Separate multiple by comma. If none is set, current interest is returned for current member (without fields weight, scope and delegate_member_ids).
Returns "result" set of:
interest (object)
issue_id (integer)
event (enum) Snapshot event, see ENUMs
member_id (integer)
weight (integer) Voting weight of member due to delegations at point in time of given event
scope (string) Scope of delegation of this member to the first member in delegate_member_ids (see ENUMs). Null for directly interested members.
delegate_member_ids (*integer) List of member ids in delegation chain. Null for directly interested members.
POST /interest
[access levels: member]
Set or remove interest to/from issue.
Request parameters:
issue_id (integer) Id of the issue to become interested in
delete (boolean) If true, remove interest
GET /issue_comment
Request parameters:
Returns "result" set of:
issue_comment (object)
issue_id (integer) Id of the commented issue
member_id (integer) Id of the member commenting the issue
changed (timestamp) Timestamp the comment was changed last time
formatting_engine
content
POST /issue_comment
[access levels: member]
Set or remove issue comment
Request parameters:
issue_id Id of the issue to comment
formatting_engine
content
Initiatives
GET /initiative
Request paramaters:
Returns "result" set of:
initiative (object)
id (integer) Primary key
issue_id (integer) Issue this initiative belongs to
name (string) Name of initiative (can't be changed later)
discussion_url (string) URL pointing to a discussion platform for this initiative
created (timestamp) Point in time, when the initiative was created
revoked (timestamp) Point in time, when the initiative was revoked. Unset, if initiative is not revoked.
revoked_by_member_id (integer) Member, who decided to revoke the initiative. Unset, if initiative is not revoked.
suggested_initiative_id (integer) Other initiative, which has been suggested, when revoking this initiative
admitted (boolean) True, when initiative has been admitted for final voting
supporter_count (integer) Count of members (including delegating members), who support this initiative
informed_supporter_count (integer) Count of members (including delegating members), who support the latest draft of this initaitive
satisfied_supporter_count (integer) Count of members (including delegating members), who support this initiative and have no suggestions marked as "must" and "unfulfilled" or "must not" and "fulfilled"
satisfied_informed_supporter_count (integer) Count of members (including delegating members), who support the latest draft of this initiative and have no suggestions marked as "must" and "unfulfilled" or "must not" and "fulfilled"
positive_votes (integer) Voters (including delegating members), who are (compared to status-quo) in favor of the initiative
negative_votes (integer) Voters (including delegating members), who are (compared to status-quo) against the initiative
direct_majority (boolean) True, if direct majority requirements are met after final voting
indirect_majority (boolean) True, if indirect majority requirements are met after final voting
schulze_rank (integer) Schulze-ranking without tie-breaking after final voting
better_than_status_quo (boolean) True, if initiative has a schulze-ranking better than the status quo (without tie-breaking)
worse_than_status_quo (boolean) True, if initiative has a schulze-ranking worse than the status quo (without tie-breaking)
reverse_beat_path (boolean) True, if there is a beat path (may include ties) from this initiative to the status quo
multistage_majority (boolean) True, if either (a) this initiative has no better rank than the status quo, or (b) there exists a better ranked initiative X, which directly beats this initiative, and either more voters prefer X to this initiative than voters preferring X to the status quo or less voters prefer this initiative to X than voters preferring the status quo to X'
eligable (boolean) True if, initiative meets direct and indirect majority requirements, has a better schulze-ranking than status quo (without tie-breaking) and depending on selected policy the initiative has no "reverse_beat_path" or "multistage_majority"'
winner (boolean) Winner of final voting
rank (integer) Unique ranking for all admitted initiatives per issue; lower ranks are better. A winner always has rank 1, but rank 1 does not imply that an initiative is winner.
GET /initiator
Request paramaters:
initiator_accepted (boolean) Select only accepted (true) or non-accepted (false) initiators
Returns "result" set of:
initiator (object)
initiative_id (integer)
member_id (integer)
accepted (boolean) True, if initiator has been accepted; false, if initiator has to be accepted by a current initiator yet.
POST /invite_initiator
[access levels: member]
Invite an initiator to an initiative.
POST /initiator
[access levels: member]
Add member as initiator to or remove initiators from an initiative, accept and reject invitations.
Request parameters:
initiative_id (integer) Initiative id
member_id (integer) Id of member to invite or remove (only for invite/delete)
accept (boolean) If true, current member accepts invitiation to initiative. If false, invitation will be rejected.
delete (boolean) If true, initiator will be immediately removed.
GET /supporter
Request parameters:
snapshot (enum) Request supporter snapshot for the given event. Valid events are 'latest', 'end_of_admission', 'half_freeze', 'full_freeze' (see ENUMs). Separate multiple by comma. If none is set, current support is returned for current member (without fields event, weight, scope and delegate_member_ids).
Returns "result" set of:
supporter (object)
initiative_id
event (enum) Snapshot event, see ENUMs
member_id
draft_id Latest draft, which has been seen and acknowleged by the member
weight (integer) Voting weight of member due to delegations at point in time of given event
scope (enum) Scope of delegation of this member to the first member in delegate_member_ids (see ENUMs). Null for directly interested members.
delegate_member_ids (*integer) List of member ids in delegation chain. Null for directly interested members.
informed (boolean) Member has seen and acknowleged last draft
satisfied (boolean) Member has no suggestions marked as "must" and "unfulfilled" or "must not" and "fulfilled"
POST /supporter
[access levels: member]
Set or remove support to/from initiative.
Request parameters:
initiative_id (integer) Initiative to support
draft_id (integer) Current draft_id (as seen by the user) to avoid race conditions
delete (boolean) If true, remove members support from initiative.
GET /battle
Request parameters:
Returns "result" set of:
battle (object)
issue_id (integer)
winning_initiative_id (integer) Initiative being preferred by "count" voters to the other initiative; unset for status quo
losing_initative_id (integer) Other initiative; unset for status quo
count (integer) Count of voters preferring the status quo or initiative with winning_initiative_id to the status quo or initiative with losing_initiative_id
Drafts
GET /draft
Request parameters:
draft_id (integer) Id of draft to return
current_draft (boolean) Return only current (latest) drafts
render_content (string) If set to html, content will be returned rendered as html
Returns "result" set of:
draft (object)
id (integer) Primary key for draft
initiative_id (integer)
created (timestamp) Point in time when this draft was submitted
author_id (integer) Member who submitted this draft
formatting_engine (string)
content (string)
POST /draft
[access levels: member]
Post a new draft. Excactly one of area_id, issue_id and initiative_id must be set.
Request parameters:
area_id (integer) Adds draft as new initiative in new issue in given area
issue_id (integer) Adds draft as new initiative in given issue
initiative_id (integer) Adds draft to given initiative
policy_id (integer) Policy of new initiative, only when creating a new initiative
initiative_name (integer) Name of new initiative, only when creating a new initiative
initiative_discussion_url (string) URL for discussion with initiators
formatting_engine (string)
content (string) The draft itself
Returns no "result" set, but following special elements in root of JSON response:
issue_id (integer)
initiative_id (integer)
draft_id (integer)
Suggestions
GET /suggestion
Request parameters:
render_content (string) If set to html, content will be returned rendered as html
Returns "result" set of:
suggestion (object)
initiative_id (integer)
id (integer) Primary key of suggestion
created (timestamp) Point in time when suggestion was submitted
author_id (integer) Member, who submitted the suggestion
name (string) Name of suggestion
formatting_engine (string) Formatting engine for suggestion text
content (string) Suggestion text
minus2_unfulfilled_count (integer) Supporters (including delegating members), who marked suggestion as "must not" and "unfulfilled"
minus2_fulfilled_count (integer) Supporters (including delegating members), who marked suggestion as "must not" and "fulfilled"
minus1_unfulfilled_count (integer) Supporters (including delegating members), who marked suggestion as "should not" and "unfulfilled"
minus1_fulfilled_count (integer) Supporters (including delegating members), who marked suggestion as "should not" and "fulfilled"
plus1_unfulfilled_count (integer) Supporters (including delegating members), who marked suggestion as "should" and "unfulfilled"
plus1_fulfilled_count (integer) Supporters (including delegating members), who marked suggestion as "should" and "fulfilled"
plus2_unfulfilled_count (integer) Supporters (including delegating members), who marked suggestion as "must" and "unfulfilled"
plus2_fulfilled_count (integer) Supporters (including delegating members), who marked suggestion as "must" and "fulfilled"
POST /suggestion
[access levels: member]
Add a new suggestion.
Request parameters:
initiative_id (int) Iniative the suggestion should be added to
name (string) Name of suggestion
formatting_engine (string) Formatting engine for suggestion text
content (string) Suggestion text
degree (int) Degree of opinion (see opinion)
fulfilled (boolean) Mark as fulfilled or not
Returns no "result" set, but following special elements in root of JSON response:
suggestion_id (int) Id of the created suggestion
GET /opinion
Request parameters:
degree (int) Degree of the opinion to look up
fulfilled (boolean) If set, look up only for fulfilled (true) or not fulfilled (false) opinions
Result set of:
opinion (object)
suggestion_id (integer)
member_id (integer)
degree (integer) "must not" (-2), "should not" (-1), "should" (1), "must" (2)
fulfilled (boolean) True, if member thinks suggestion is fulfilled, false if not
POST /opinion
[access levels: member]
Set or remove your opinion for a suggestion.
Request parameters:
suggestion_id (integer) Suggestion to rate
degree (integer) Grade of the opinion, can be -2, -1, 1 or 2
fulfilled (boolean) True if suggestion is fulfilled, false if not
delete (boolean) If set, opinion will be deleted
Delegations
GET /delegation
[access levels: member, full, pseudonym]
Get information about unit, area and issue delegations.
Request parameters:
direction (string) Get only incoming or outgoing delegation by "in" or "out", omit for both
scope (string) Get delegations only for given scope, can be "unit", "area", "issue", seperate multiple with comma
Returns "result" set of:
delegation (object)
unit_id (integer)
area_id (integer)
issue_id (integer)
scope (string) Delegation scope, can be "unit", "area", "issue"
truster_id (integer) Id of the member trusting
trustee_id (integer) Id of the trusted member
POST /delegation
[access levels: member]
Set or remove a delegation.
Request parameters:
unit_id (integer) Set/delete delegation for given unit
area_id (integer) Set/delete delegation for given area
issue_id (integer) Set/delete delegation for given issue
trustee_id (integer) Delegate to given member, omit key to delete delegation, omit value (empty string) to abandon
Voting
GET /voter
Request parameters:
Returns "result" set of:
voter (object)
issue_id (integer)
member_id (integer)
weight (integer) Voting weight of member due to delegations
GET /delegating_voter
Request parameters:
Returns "result" set of:
voter (object)
issue_id (integer)
member_id (integer)
weight (integer) Voting weight of member due to delegations
scope (enum) Scope of delegation of this member to the first member in delegate_member_ids (see ENUMs). Null for direct voters.
delegate_member_id (*integer) List of member ids in delegation chain. Null for direct voters.
GET /vote
[access levels: member, full, pseudonym]
Request parameters:
Returns "result" set of:
vote (object)
issue_id (integer)
initiative_id (integer)
member_id (integer)
grade (integer) Higher numbers represent better ranking. The status quo is implicitly ranked as zero, thus positive numbers represent approvals and negative numbers represent disapprovals.
POST /vote
[access levels: member]
Vote for an issue or remove vote. Initiatives without a grade set will be
Request parameters:
issue_id (integer) Issue to vote on
initiative_<initiative id> (integer) Grade for given initiative_id
delete (boolean) If true, delete voting for issue
GET /non_voter
[access levels: member] Request parameters
Returns "result" set of:
non_voter (object)
issue_id
POST /non_voter
[access levels: member]
Request parameters:
issue_id (int) Issue not to vote for
delete (boolean)
GET /voting_comment
Request parameters:
Returns "result" set of:
voting_comment (object)
issue_id (integer) Issue to comment
member_id (integer) Member commenting the issue
changed (timestamp) Point in time when comment was created or updated
formatting_engine (string) Formatting engine for comment text
content (string) Comment text
POST /voting_comment
[access levels: member]
Set or remove issue comment
Request parameters:
issue_id (integer) Issue to comment
formatting_engine (string) Formatting engine for comment text
content (string) Comment text
Events
GET /event
Returns "result" set of:
event (object)
id (integer) Primary key for event
occurence (timestamp) Timestamp of event
event (enum) Event type (see ENUMs)
member_id (integer) Member who caused the event (optional)
issue_id (integer) Issue affected by the event
state (enum) State of the issue at the time of the event
initiative_id (integer) Initiative affected by the event (optional)
draft_id (integer) Draft affected by the event (optional)
suggestion_id (integer) Suggestion affected by the event (optional)
GET /ignored_member
[access levels: member]
Returns "result" set of:
ignored_member (object)
other_member_id (integer) Id of the ignored member
POST /ignored_member
[access levels: member]
Request parameters:
other_member_id (integer) Member to be ignored (or unignored)
delete (boolean) If set, member will be unignored
GET /ignored_initiative
[access levels: member]
Returns "result" set of:
ignored_initiative (object)
initiative_id (integer) Ignored initiative
POST /ignored_initiative
[access levels: member]
Request parameters:
initiative_id (integer) Initiative to be ignored (or unignored)
delete (boolean) If set, initiative will be unignored
Settings
GET /setting
[access levels: member]
Get frontend related member settings. Only one of [unit|area|issue|initiative|suggestion]_id may be set. If omited, global member setting will be returned.
Request parameters:
unit_id (integer)
area_id (integer)
issue_id (integer)
initiative_id (integer)
suggestion_id (integer)
other_member_id (integer)
key (string)
subkey (string)
POST /setting
[access levels: member]
Set frontend related member Setting. Only one of [unit|area|issue|initiative|suggestion]_id may be set. If omited, global member setting will be returned. Existant settings will be overwritten. To delete setting, ommit value.
Request parameters:
unit_id (integer)
area_id (integer)
issue_id (integer)
initiative_id (integer)
suggestion_id (integer)
other_member_id (integer)
key (string)
subkey (string)
value (string)
Attachments
-
lf-schaubild.png
(57.4 KB) -
added by dark 10 months ago.
