| Version 132 (modified by dark, 21 months ago) (diff) |
|---|
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.
Request parameters
Request parameters can be either submitted as GET URL parameters for any type of request or submitted www-url-encoded in the body of a POST request. If both types of parameters are submitted with a POST request, they will be merged with(?) values from body having precedence.
Encoding
Strings needs to be url encoded. Integers needs to be ASCII encoded as string. Boolean values must be encoded as letter one ('1') meaning true and empty string meaning false.
Resulting answer
The server will answer to the request with a JSON document containing a result object with the following structure:
{
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
}
Except of the status field all fields are optional depending on the request.
status string
A string indicating if the request could be executed.
ok Everything went fine and a result is delivered.
forbidden Current session is not allowed.
notfound The desired request is not available.
unprocessable The request contains invalid parameters or an invalid combination of parameters.
error An error occurred while processing your request.
error string
If an error occured (status not 'ok') the result object contains a text description of the error.
result list
The objects which were requested. The type of objects depends on the request and is described for any request below.
members, suggestions, initiatives, issues, areas, units, policies lists
These lists of the corresponding objects are included in the resulting object when request with include_* parameters. For more information see section Fetch related data in same request below.
issue_id, initiative_id, draft_id
These ids area included in the resulting object when creating a new draft.
Encoding of the result
The data types known to JSON (strings, integer, boolean) are encoded as specified. Timestamps in reply are encoded like '2009-08-07T12:34:56.789Z'// ( ISO 8601 time format). Intervals in reply are encoded like { weeks: 2 } or like { months: 1, days: 23 } ([ http://www.postgresql.org/docs/9.0/static/datatype-datetime.html#INTERVAL-STYLE-OUTPUT-TABLE ]).
Application authentication and session management
The authentication and session management is not yet specified. For testing purposes a preliminary very simple authentication interface is described as follows.
POST /session
Request a session key for a given application key. The session key has to be added to all subsequent requests as session_key parameter. Session can be terminated at any time, so applications have to be aware of that.
Request parameters:
key (string) Registered application key
Returns:
session_key (string)
Security
It is highly recommended to make the service ONLY available via SSL! The application itself is not providing SSL itself, so please use a SSL proxy for that.
TODO!
Generic request options
For many request can some or all of the following generic request options be used. For each request is described below which generic requests are available.
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 resulting answer section above. The data is delivered as associative array with the id of the object 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
TODO
Limit and offset
limit (integer) Maximum numbers of results to return (default 101, maximum 1001)
offset (integer) Skip how many result
Member options
member_id (integer) Member id to lookup, seperate multiple ids with a comma
member_disabled (boolean) Return disabled units instead of active when set to true or 1
member_search (string) Search term, seperate 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
policy_id (integer) Policy id to lookup, seperate multiple ids with comma
policy_order_by_name (boolean) Order result by policy name
Unit options
unit_id (integer) Unit id to lookup, seperate multiple ids with comma
unit_parent_id (integer) Lookup only units which are child of given parent unit
unit_without_parent (boolean) Lookup only units in root
unit_disabled (boolean) Return disabled units instead of active when set true
unit_order_by_path (integer) Order result by unit path name
Area options
<include unit_options>
area_id (int) Area id to lookup, seperate multiple ids with a comma
area_disabled (boolean) Return disable units insted of active when set true
area_order_by_population (integer) Order result descending by area member count
Issue options
<area_options>
<policy_options>
issue_id (int) Issue id to lookup, seperate multiple ids with a comma
issue_state (string) Current state of issue, seperate multiple states with comma, ommit 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 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 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 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 issues
issue_closed_after (timestamp) Select issues closed after given timestamp
issue_closed_before (timestamp) Select issues closed before given timestamp
issue_ranks_available (boolean) Select issues for which ranks are available
issue_cleaned (boolean) Select issues which are cleaned
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
issue_order_by_creation (integer) Order result descending by issue creation timestamp
issue_order_by_state_time_left (integer) Order result by time left in current issue state
issue_order_by_interest (integer) Order result descending by issue interest count
Initiative options
<issue_options>
<member_options prefixed with initiator_>
<member_options prefixed with supporter_>
initiative_id (int) Initiative id to lookup, seperate multiple ids with a comma
initiative_created_after (timestamp)
initiative_created_before (timestamp)
initiative_revoked (boolean)
initiative_revoked_after (timestamp)
initiative_revoked_before (timestamp)
initiative_revoked_by_member_id (integer)
initiative_admitted (boolean)
initiative_admitted_after (timestamp)
initiative_admitted_before (timestamp)
initiative_suggested_initiative_id (integer)
initiative_supporter_count_below (integer)
initiative_supporter_count_above (integer)
initiative_attainable (boolean)
initiative_favored (boolean)
initiative_unfavored (boolean)
initiative_preliminary_rank (integer)
initiative_final_rank (integer)
initiative_disqualified (boolean)
initiative_winner (boolean)
initiative_search (string)
initiative_order_by_supporter (integer) Order result descending by initiative suppotert count
initiative_order_by_creation (integer) Order result descending by initiative creation date
Suggestion options
<initiative_options>
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
Pseudo states "open" and "close" includes the corresponding states.
General information
GET /info
[access levels: member, full, pseudonym, anonymous] Get current version of core and api and access level of current connection. Clients should check API version after startup before doing any other request.
No request parameters
Returns:
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
settings (object) A nested structure of settings, taken from config.settings
GET /member_count
[access levels: member, full, pseudonym, anonymous]
No request parameters
Returns:
member_count (integer) Count of members currently having voting right
member_count_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 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:
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:
<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:
Returns set of:
member (object)
id (int)
name (string)
identification (string)
organizational_unit (string)
internal_posts (string)
realname (string)
birthday (date)
address (string)
email (string)
xmpp_address (string)
website (string)
phone (string)
mobile_phone (string)
profession (string)
external_memberships (string)
external_posts (string)
statement (string)
active (boolean) Memberships, support and votes are taken into account when corresponding members are marked as active. When the user does not log in for an extended period of time, this flag may be set to FALSE. If the user is not locked, he/she may reset the active flag by logging in.
locked (boolean) Locked members can not log in.
created (timestamp)
last_login_public (date) Date of last login (time stripped for privacy reasons, updated only after day change)
POST /member
[access levels: member]
Update personal profile data of current member.
Request parameters:
organizational_unit (string)
internal_posts (string)
realname (string)
birthday (date)
address (string)
email (string)
xmpp_address (string)
website (string)
phone (string)
mobile_phone (string)
profession (string)
external_memberships (string)
external_posts (string)
statement (string)
GET /member_history
[access levels: member, full]
Request parameters:
Returns set of:
member_history_entry (object)
until (timestamp)
active (boolean)
name (string)
GET /member_image
[access levels: member, full]
Request parameters:
type (string) Type of image, can be "avatar" or "portrait"
Returns set of:
member_image (object)
member_id (int8)
type (string) Image type
mime_type (string) Mime-type of the image, ie. image/jpeg
data (binary) The data itself, encoded as ???
POST /member_image
[access levels: member]
Update avatar or portrait image.
GET /contact
[access levels: member, full, pseudonym]
Request parameters:
Returns set of:
contact (object)
member_id (int)
other_member_id (int)
public (int)
POST /contact
[access levels: member]
Set or remove, publish and unpublish a contact.
GET /privilege
[access levels: member, full, pseudonym]
Request parameters:
Returns set of:
privilege (object)
unit_id (int)
admin_manager (boolean)
unit_manager (boolean)
area_manager (boolean)
voting_right_manager (boolean)
voting_right (boolean)
Policies
GET /policy
Get informations about policies.
Request parameters:
Returns set of:
policy (object)
id (int)
active (boolean)
index (int)
name (string)
description (string)
admission_time (interval)
discussion_time (interval)
verification_time (interval)
voting_time (interval)
issue_quorum_num (int)
issue_quorum_den (int)
majority_num (int)
majority_den (int)
majority_strict (boolean)
Units
GET /unit
Get information about units.
Request parameters:
Returns set of:
unit (object)
id (int) Id of the unit
parent_id (int) Id of the parent unit (null if unit in root level)
active (boolean) True if unit is active, false if unit is deactivated
name (string) Name of the unit
path (string)
description (string) Description of the unit
member_count (int) Count of currently active members with voting right for this unit. Value is calculated periodically by the core.
Areas
GET /area
Request parameters:
Returns:
area (object)
id (int)
unit_id (int)
active (boolean)
name (string)
description (string)
direct_member_count (int)
member_weight (int)
autoreject_weight (int)
allowed_policies (Set of policies)
GET /allowed_policy
Request parameters:
Returns:
allowed_policy (object)
policy_id (int)
default_policy (boolean)
GET /membership
Request parameters:
POST /membership
[access levels: member]
Set or remove membership to/from area.
Issues
GET /issue
Request parameters:
Returns set of:
issue (object)
id (integer)
area_id (integer)
policy_id (integer)
state (string)
created (timestamp)
accepted (timestamp)
half_frozen (timestamp)
fully_frozen (timestamp)
closed (timestamp)
ranks_available (boolean)
cleaned (timestamp)
admission_time (interval)
discussion_time (interval)
verification_time (interval)
voting_time (interval)
snapshot (interval)
latest_snapshot_event (string)
population (integer)
vote_now (integer)
vote_later (integer)
voter_count (integer)
GET /interest
Request parameters:
snapshot (string) Reply interest for given event. Valid are 'latest', 'end_of_admission', 'half_freeze', 'full_freeze'. Seperate multiple with comma. If none is set, current interest is returned for current member (without fields event, weight, delegation_scope and delegate_member_ids).
Returns:
interest (object)
issue_id (integer)
member_id (integer)
event (string)
interested (boolen) True if member is interested at event. False if member is not interested but in population of issue at event.
weight (integer) Voting weight of the member at event
delegation_scope (string) Scope of outgoing delegation ('unit', 'area', 'issue'). Null for direct interested mebers.
delegate_member_ids (*integer) List of member ids in delegation chain. Null for direct interested mebers.
POST /interest
[access levels: member]
Set or remove interest to/from issue.
GET /issue_comment
Request parameters:
POST /issue_comment
[access levels: member]
Set or remove issue comment
Initiatives
GET /initiative
Request paramaters:
Returns:
initiative (object)
id (integer)
issue_id (integer)
name (string)
discussion_url (string)
created (timestamp)
revoked (timestamp)
revoked_by_member_id (integer)
suggested_initiative_id (integer)
admitted (boolean)
supporter_count (integer)
informed_supporter_count (integer)
satisfied_supporter_count (integer)
satisfied_informed_supporter_count (integer)
positive_votes (integer)
negative_votes (integer)
attainable (boolean)
favored (boolean)
unfavored (boolean)
preliminary_rank (integer)
final_rank (integer)
disqualified (boolean)
winner (boolean)
initiators (set of members)
GET /initiator
Request paramaters:
Returns:
initiator (object)
initiative_id (integer)
member_id (integer)
GET /supporter
Request parameters:
snapshot (string) Reply interest for given event. Valid are 'latest', 'end_of_admission', 'half_freeze', 'full_freeze'. Seperate multiple with comma. If none is set, current interest is returned for current member (without fields event, weight, delegation_scope and delegate_member_ids).
Returns:
initiative_id
member_id
draft_id
event (string)
interested (boolen) True if member is interested at event. False if member is not interested but in population of issue at event.
weight (integer) Voting weight of the member at event
delegation_scope (string) Scope of outgoing delegation ('unit', 'area', 'issue'). Null for direct interested mebers.
delegate_member_ids (*integer) List of member ids in delegation chain. Null for direct interested members.
informed
satisfied
POST /supporter
[access levels: member]
Add members support to an initiative.
Request parameters:
initiative_id (integer) Id of the initiative
draft_id (integer) Current draft_id (as seen by the user) to avoid race conditions
delete (boolean) If true, remove members support from initiative.
Set or remove support to/from initiative.
GET /battle
Request parameters:
Returns set of:
battle (object)
issue_id (integer)
winning_initiative_id (integer)
losing_initative_id (integer)
count (integer)
POST /invite_initiator
[access levels: member]
Invite an initiator to an initiative.
POST /initiator
[access levels: member]
Accept or reject becoming initiator of an initiative.
Drafts
GET /draft
Request parameters:
draft_id (integer) Id of draft to return
current_draft (boolean) Return only current drafts
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 to discussion with initiatior
formatting_engine (string)
content (string) The draft itself
For this request the resulting object contains 3 additional values: issue_id, initiative_id, draft_id.
Suggestions
GET /suggestion
Request parameters:
Returns set of:
suggestion (object)
id
created
author_id
formatting_engine (string)
content (string) The draft itself
name
text_search_data
minus2_unfulfilled_count
minus2_fulfilled_count
minus1_unfulfilled_count
minus1_fulfilled_count
plus1_unfulfilled_count
plus1_fulfilled_count
plus2_unfulfilled_count
plus2_fulfilled_count
POST /suggestion
[access levels: member]
Add a new suggestion.
Request parameters:
initiative_id (int) Id of the iniative the suggestion should be added to
name (string) Title of the suggestions
formatting_engine (string)
content (string) Content of the suggestion
degree (int) Degree of opinion (see opinion)
fulfilled (boolean) Mark as fulfilled or not
Result:
suggestion_id (int) Id of the created suggestion
GET /opinion
Request parameters:
degree (int) Degree of the opinion to look up
fulfilled (boolean) If set, look up only for fulfilled (true) or not fulfilled (false) opinions
Result set of:
suggestion_id (int) The id of the suggestion the opinion is about
member_id (int) Id of the member of the opinion
degree (int) Grade of the opinion, can be -2, -1, 1 or 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 (int) Id of the suggestion to rate
degree (int) Grade of the opinion, can be -2, -1, 1 or 2
fulfilled (boolean) True if suggestion is fulfilled, false if not
delete (boolean) If set, opinion will be deleted
Delegations
GET /delegation
[access levels: member, full, pseudonym]
Get information about unit, area and issue delegations.
Request parameters:
direction (string) Get only incoming or outgoing delegation by "in" or "out", omit for both
scope (string) Get delegations only for given scope, can be "unit", "area", "issue", seperate multiple with comma
Returns:
unit_id (integer)
area_id (integer)
issue_id (integer)
scope (string) Delegation scope, can be "unit", "area", "issue"
truster_member_id (integer) Id of the member trusting
trustee_member_id (integer) Id of the trusted member
POST /delegation
[access levels: member]
Set or remove a delegation.
Request parameters:
unit_id (integer) Set delegation for given unit
area_id (integer) Set delegation for given area
issue_id (integer) Set delegation for given issue
trustee_id (integer) Delegate to given member, ommit to delete delegation, ommit value to abandon
Voting
GET /vote
[access levels: member, full, pseudonym]
(includes non_voter, direct_voter, delegating_voter, voting_comment) Request parameters:
Returns:
issue_id (int)
initiative_id (int)
member_id (int)
grade (int)
POST /vote
[access levels: member]
Vote for an issue or remove vote. Initiatives without a grade set will be
Request parameters:
issue_id (int) Id of the issue to vote for
initiative_<initiative id> (int) Set grade for given initiative_id
Events
GET /event
Returns set of:
id (int) Id of the event
occurence (timestamp) Timestamp the event occurred
event (enum) Type of the event
member_id (int) Id of the member who caused the event (optional)
issue_id (int) Id of the issue affected by the event
state (enum) State of the issue at the time of the event
initiative_id (int) Id of the initiative affected by the event (optional)
draft_id (int) Id of the draft affected by the event (optional)
suggestion_id (int) Id of the suggestion affected by the event (optional)
GET /ignored_member
[access levels: member]
Returns set of:
member_id (int) Id of the ignored member
POST /ignored_member
[access levels: member]
Request parameters:
member_id (int) Id of the member to be ignored
delete (boolean) If set, member will be unignored
GET /ignored_initiative
[access levels: member]
Returns set of:
initiative_id (int) Id of the ignored initiative
POST /ignored_initiative
[access levels: member]
Request parameters:
initiative_id (int) Id of the initiative to be ignored
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 ommited, global member setting will be returned.
Request parameters:
unit_id (integer)
area_id (integer)
issue_id (integer)
initiative_id (integer)
suggestion_id (integer)
member_id (integer)
key (string)
key2 (string)
POST /setting
[access levels: member]
Set frontend related member Setting. Only one of [unit|area|issue|initiative|suggestion]_id may be set. If ommited, 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)
member_id (integer)
key (string)
key2 (string)
value (string)
Attachments
-
lf-schaubild.png
(57.4 KB) -
added by dark 2 years ago.
