wiki:API

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.

Access levels

The API supports the following access levels:

  • member
  • full
  • pseudonym
  • anonymous
  • none

Each session has set a current access level. The access level for public read only access (none, anonymous, pseudonym or full) is set by configuration. Write privileges are only granted to sessions with access level "member" connected to a member having unit privileges for the requested action.

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 API authentication and session management is not yet specified completely. Until the authentication and authorization is finally specified, the following preliminary simple authentication may be used:

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)


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_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)



Authentication and authorization

GET /

[access levels: member, full, pseudonym, anonymous]

This is a special API method delivering a HTML document intended to be used directly by a user within his or her web browser to login into the LiquidFeedback security center or to authorize an API consumer. This API method must never be called by an API consumer directly, the application must (re-)direct the users web browser to this API method. The interface implements the OAuth 2.0 authorization framework. How to use this interface in combination with the POST /token method is specified in the LiquidFeedback API security specification.

Request parameters:

response_type (string) Either 'code' for OAuth authorization code grant or 'token' for OAuth implicit grant (optional)

client_id (string) Client identifier, API consumers registered by the administrator use the issued client identifier, other API consumers must send their redirection endpoint as client identifier (mandatory if response_type is set)

scope (string) The requested [access level] (mandatory if response_type is set)

redirect_uri (string) Redirection endpoint of API consumer, for API consumers registered by the administrator defaults to the redirect_uri registered by the administrator, for other API consumers defaults to the client_id sent in the same request, in any case: If redirect_uri is set, it must not differ from the default value (optional)

state (string) Passed value, which will be send back to the API consumer redirection endpoint, to be used for Cross Site Request Forgery protection (optional)

Response

A HTML document to be displayed by a web browser, i.e. a regular web page.

POST /token

Requests an access token and optionally a refresh token by submitting either pre shared client credentials, an authorization code obtained by the GET / interface or an refresh token obtained by a previous request of this method. The interface implements the OAuth 2.0 authorization framework. How to use this interface in combination with the GET / method is specified in the LiquidFeedback API security specification.

Request headers:

Authorization (string) Client credentials (client_id and client_secret) encoded according to HTTP Basic Authentication Scheme (mandatory if API consumer has a registered client secret, unless client_id and client_secret are sent as request parameters)

Request parameters:

grant_type (string) 'client_credentials' for OAuth client credentials grant, 'authorization_code' for OAuth authorization code grant, 'refresh_token' for OAuth access token and refresh token refreshing (mandatory)

single_token (boolean) Automatically invalidate other previously issued refresh tokens (optional, allowed if grant_type is set to 'authorization_token')

client_id (string) Client identifier, API consumers registered by the administrator use the issued client identifier, other API consumers must send their redirection endpoint as client identifier (mandatory if grant_type is set to 'authorization_code' or if API consumer has a registered client secret, but forbidden if authorization header is set)

client_secret (string) Client secret (mandatory if API consumer has a registered client secret, but forbidden if authorization header is set)

refresh_token (string) Refresh token for OAuth access token and referesh token refreshing (mandatory if grant_type is set to 'referesh_token')

scope (string) The requested [access level], defaults to scope sent with GET / method and must not exceed it (optional)

code (string) OAuth Authorization Code as received by the API consumer redirection endpoint after authorization (mandatory if grant_type is set to 'authorization_code')

redirect_uri (string) Redirection endpoint of API consumer as sent with GET / method (mandatory if redirect_uri was sent with GET / method)

Response: Returns no "result" set, but following special elements in root of JSON response:

access_token (string) The access token itself, to be used in subsequent API requests

token_type (string) Always set to 'Bearer', must be checked by API consumer

expires_in (integer) Maximum lifetime of access token in seconds

refresh_token (string) A refresh token to be used in subsequent access token and refresh token refreshing (not set if request parameter grant_type was set to 'client_credentials')

error (string) Error identifier according to OAuth (only set if an error occured)

error_description (string) Error description (only set if an error occured)

error_uri (string) Error URI (only set if an error occured)

In case of an error during authorization this method responds with HTTP error status 400.



System 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:

<member options>

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:

<member options>

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"

<member options>

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:

<member options>

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:

<unit options>

<member options>

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:

<policy options>

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:

<unit options>

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:

<area options>

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:

<area options>

<policy options>

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:

<area options>

<member options>

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:

<issue options>

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

phase_finished (boolean) True, if current phase is finished but next phase ist not started yet

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:

<issue options>

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:

<issue options>

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:

<issue options>

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:

<initiative options>

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)

polling (boolean) True if initiative was created in polling mode

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"

harmonic_weight (float) Harmonic weight of current initiative for ordering

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:

<initiative options>

<member options>

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:

<initiative options>

<member options>

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:

<initiative options>

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:

<initiative options>

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:

<suggestion options>

<member options>

rendered_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"

proportional_order (integer) Proportional order for ordering

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:

<suggestion options>

<member options>

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:

<initiative options>

<member options>

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:

<issue options>

<member options>

rendered_content (string)

Returns "result" set of:

voter (object)

issue_id (integer)

member_id (integer)

weight (integer) Voting weight of member due to delegations

formatting_engine (string)

comment (string)

POST /voter

[access levels: member]

Vote for an issue or remove vote.

Request parameters:

issue_id (integer) Issue to vote on

initiative_<initiative id> (integer) Grade for given initiative_id

formatting_engine (string) Formatting engine for voting comment

comment (string) Voting comment as wiki text

delete (boolean) If true, delete voting for issue

GET /delegating_voter

Request parameters:

<issue options>

<member options>

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:

<initiative options>

<member options>

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.

GET /non_voter

[access levels: member] Request parameters

<issue options>

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)



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)

Last modified 4 years ago Last modified on Mar 22, 2013, 7:43:48 AM

Attachments (1)

Download all attachments as: .zip