= LiquidFeedback API specification (WORKING DRAFT) * [#Overviewofdatastructures Overview of data structures] * [#Generalinformation General information] * [#Accesslevels Access levels] * [#Requestparameters Request parameters] * [#Response Response] * [#Applicationauthenticationandsessionmanagement Application authentication and session management] * [#Snapshots Snapshots] * [#Genericrequestparameters Generic request parameters] * [#Fetchrelateddatainsamerequest Fetch related data in same request] * [#Ordering Ordering] * [#Limitandoffset Limit and offset] * [#Memberoptions Member options] * [#Policyoptions Policy options] * [#Unitoptions Unit options] * [#Areaoptions Area options] * [#Issueoptions Issue options] * [#Initiativeoptions Initiative options] * [#Suggestionoptions Suggestion options] * [#ENUMs ENUMs] * [#Authenticationandauthorization Authentication and authorization] * [#GET GET /] * [#POSTtoken POST /token] * [#Systeminformation System information] * [#GETinfo GET /info] * [#GETmember_count GET /member_count] * [#GETcontingent GET /contingent] * [#POSTecho_test POST /echo_test] * [#Members Members] * [#GETmember GET /member] * [#POSTmember POST /member] * [#GETmember_history GET /member_history] * [#GETmember_image GET /member_image] * [#POSTmember_image POST /member_image] * [#GETcontact GET /contact] * [#POSTcontact POST /contact] * [#GETprivilege GET /privilege] * [#Policies Policies] * [#GETpolicy GET /policy] * [#Units Units] * [#GETunit GET /unit] * [#Areas Areas] * [#GETarea GET /area] * [#GETallowed_policy GET /allowed_policy] * [#GETmembership GET /membership] * [#POSTmembership POST /membership] * [#Issues Issues] * [#GETissue GET /issue] * [#GETinterest GET /interest] * [#POSTinterest POST /interest] * [#GETissue_comment GET /issue_comment] * [#POSTissue_comment POST /issue_comment] * [#Initiatives Initiatives] * [#GETinitiative GET /initiative] * [#GETinitiator GET /initiator] * [#POSTinitiator POST /initiator] * [#GETsupporter GET /supporter] * [#POSTsupporter POST /supporter] * [#GETbattle GET /battle] * [#Drafts Drafts] * [#GETdraft GET /draft] * [#POSTdraft POST /draft] * [#Suggestions Suggestions] * [#GETsuggestion GET /suggestion] * [#POSTsuggestion POST /suggestion] * [#GETopinion GET /opinion] * [#POSTopinion POST /opinion] * [#Delegations Delegations] * [#GETdelegation GET /delegation] * [#POSTdelegation POST /delegation] * [#Voting Voting] * [#GETvoter GET /voter] * [#POSTvoter POST /voter] * [#GETdelegating_voter GET /delegating_voter] * [#GETvote GET /vote] * [#GETnonvoter GET /non_voter] * [#POSTnonvoter POST /non_voter] * [#Events Events] * [#GETevent GET /event] * [#GETignored_member GET /ignored_member] * [#POSTignored_member POST /ignored_member] * [#GETignored_initiative GET /ignored_initiative] * [#POSTignored_initiative POST /ignored_initiative] * [#Settings Settings] * [#GETsetting GET /setting] * [#POSTsetting POST /setting] [[BR]][[BR]] = Overview of data structures [[Image(lf-schaubild.png)]] [[BR]][[BR]] = 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 [#Fetchrelateddatainsamerequest 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'// ([http://en.wikipedia.org/wiki/ISO_8601 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 ]). [[BR]] == Application authentication and session management The [[API_security|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) [[BR]] == 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". [[BR]][[BR]] = 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 [http://dev.liquidfeedback.org/trac/lf/wiki/API#Response 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. <[#Unitoptions 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. <[#Areaoptions area options]> (Where issue options are available, area options can be used as well) <[#Policyoptions 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. <[#Issueoptions issue options]> (Where initiative options are available, issue options can be used as well) <[#Memberoptions member options] prefixed with "initiator_"> (Where initiative options are available, member options can be used with "initiator_" prefix to refer to initiators of initiatives) <[#Memberoptions 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. <[#Initiativeoptions initiative options]> (Where suggestion options are available, initiative options can be used as well) //suggestion_id// (int) [[BR]][[BR]] = 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) [[BR]][[BR]] = 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 [http://tools.ietf.org/html/draft-ietf-oauth-v2 OAuth 2.0 authorization framework]. How to use this interface in combination with the POST /token method is specified in the [[API_security|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 [http://tools.ietf.org/html/draft-ietf-oauth-v2 OAuth 2.0 authorization framework]. How to use this interface in combination with the GET / method is specified in the [[API_security|LiquidFeedback API security specification]]. Request headers: //Authorization// (string) Client credentials (client_id and client_secret) encoded according to [http://tools.ietf.org/html/rfc2617 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. [[BR]][[BR]] = 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) Result parameters in root of JSON response: (any) [[BR]][[BR]] = 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: <[#Memberoptions 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: <[#Memberoptions 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" <[#Memberoptions 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: <[#Memberoptions 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: <[#Unitoptions unit options]> <[#Memberoptions 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 [[BR]][[BR]] = Policies == GET /policy Get informations about policies. Request parameters: <[#Policyoptions 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 [[BR]][[BR]] = Units == GET /unit Get information about units. Request parameters: <[#Unitoptions 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. [[BR]][[BR]] = Areas == GET /area Request parameters: <[#Areaoptions 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: <[#Areaoptions area options]> <[#Policyoptions 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: <[#Areaoptions area options]> <[#Memberoptions 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 [[BR]][[BR]] = Issues == GET /issue Request parameters: <[#Issueoptions 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 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 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: <[#Issueoptions 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 ENUMs]). Separate multiple by comma. Returns "result" set of: //population// (object) //issue_id// (integer) //event// (enum) Snapshot event, see [#ENUMs 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 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: <[#Issueoptions issue options]> //snapshot// (enum) Request interest snapshot for the given event. Valid events are 'latest', 'end_of_admission', 'half_freeze', 'full_freeze' (see [#ENUMs 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 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 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: <[#Issueoptions 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// [[BR]][[BR]] = Initiatives == GET /initiative Request paramaters: <[#Initiativeoptions 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: <[#Initiativeoptions initiative options]> <[#Memberoptions 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: <[#Initiativeoptions initiative options]> <[#Memberoptions member options]> //snapshot// (enum) Request supporter snapshot for the given event. Valid events are 'latest', 'end_of_admission', 'half_freeze', 'full_freeze' (see [#ENUMs 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 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 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: <[#Initiativeoptions 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 [[BR]][[BR]] = Drafts == GET /draft Request parameters: <[#Initiativeoptions 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) [[BR]][[BR]] = Suggestions == GET /suggestion Request parameters: <[#Suggestionoptions suggestion options]> <[#Memberoptions 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: <[#Suggestionoptions suggestion options]> <[#Memberoptions 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 [[BR]][[BR]] = Delegations == GET /delegation ^[access levels: member, full, pseudonym]^ Get information about unit, area and issue delegations. Request parameters: <[#Initiativeoptions initiative options]> <[#Memberoptions 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 [[BR]][[BR]] = Voting == GET /voter Request parameters: <[#Issueoptions issue options]> <[#Memberoptions 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_// (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: <[#Issueoptions issue options]> <[#Memberoptions 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 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: <[#Initiativeoptions initiative options]> <[#Memberoptions 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 <[#Issueoptions 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) [[BR]][[BR]] = 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 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 [[BR]][[BR]] = 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)