projects.mako.cc - selectricity-live/blob - app/apis/selectricity_api.rb

   1 # Selectricity: Voting Machinery for the Masses
   2 # Copyright (C) 2007, 2008 Benjamin Mako Hill <mako@atdot.cc>
   3 # Copyright (C) 2007 Massachusetts Institute of Technology
   4 #
   5 # This program is free software: you can redistribute it and/or modify
   6 # it under the terms of the GNU Affero General Public License as
   7 # published by the Free Software Foundation, either version 3 of the
   8 # License, or (at your option) any later version.
   9 #
  10 # This program is distributed in the hope that it will be useful, but
  11 # WITHOUT ANY WARRANTY; without even the implied warranty of
  12 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13 # Affero General Public License for more details.
  14 #
  15 # You should have received a copy of the GNU Affero General Public
  16 # License along with this program.  If not, see
  17 # <http://www.gnu.org/licenses/>.
  18
  19 class QuickVoteStruct < ActionWebService::Struct
  20   member :name, :string
  21   member :description, :string
  22   member :candidate_ids, [:int]
  23   member :candidate_names, [:string]
  24   member :id, :int
  25 end
  26
  27 class QuickVoterInfo < ActionWebService::Struct
  28   member :voter_id, :int
  29   member :voter_session_id, :string
  30   member :voter_ipaddress, :string
  31   member :vote_time, :int
  32   member :vote, [:int]
  33 end
  34
  35 class QuickVoteResultStruct < ActionWebService::Struct
  36   member :plurality_winners, [:int]
  37   member :approval_winners, [:int]
  38   member :condorcet_winners, [:int]
  39   member :ssd_winners, [:int]
  40   member :borda_winners, [:int]
  41 end
  42
  43
  44 class QuickVoteCandidateMap < ActionWebService::Struct
  45   member :candidate_ids, [:int]
  46   member :candidate_names, [:string]
  47 end
  48
  49
  50 # An API for interfacing with Selectricity
  51 # This allows for things like XML-RPC to have a unified interface
  52 # The implementation is elsewhere.
  53
  54 class SelectricityAPI < ActionWebService::API::Base
  55
  56   # Casts a quickvote.  Expects a quickvote name, a voter ID, and a list
  57   # of candidate ID's respectively.  Returns a string containing any
  58   # potential errors that occurred in the process.
  59   api_method :cast_quickvote, :expects => [:string, :int, [[:int]]],
  60              :returns => [:string]
  61
  62   # Return the results of a QuickVote.  Takes in the name of a
  63   # quickvote, and returns a structure as described by
  64   # QuickVoteResultStruct
  65
  66   api_method :get_quickvote_results, :expects => [:string],
  67              :returns => [QuickVoteResultStruct]
  68
  69   # Returns information regarding all the candidates in a QuickVote
  70   # Takes in a QuickVote name, and returns the list of names and ID's of
  71   # candidates This can be useful for presenting the user with a list of
  72   # readable names, while the software sends results to us in the
  73   # numeric ID's we require. The two lists are in respective order.
  74
  75   api_method :get_quickvote_candidate_map, :expects => [:string],
  76              :returns => [QuickVoteCandidateMap]
  77
  78   # Converts QuickVote candidate ID's to names Takes in a QuickVote name
  79   # and a list of candidate ID's, and returns the names of each
  80   # candidate. Useful for doing just a few lookups; it's more efficient
  81   # to use get_quickvote_candidate_map for presenting info about an
  82   # entire election.
  83
  84   api_method :quickvote_candidate_ids_to_names,
  85              :expects => [:string,[:int]], :returns => [[:string]]
  86
  87   # Get information on all the votes cast in a QuickVote Takes in the
  88   # name of a QuickVote, returns an array of QuickVoterInfo structures.
  89   api_method :get_quickvote_votes, :expects => [:string],
  90              :returns => [ [QuickVoterInfo] ]
  91
  92   # Gets a list of all QuickVotes in the system.
  93   api_method :list_quickvotes, :expects => [],
  94              :returns => [[QuickVoteStruct]]
  95
  96   # Gets information on a particular QuickVote.  Takes in a QuickVote
  97   # name.
  98   api_method :get_quickvote, :expects => [:string],
  99              :returns => [QuickVoteStruct]
 100
 101   # Create a QuickVote Pass in a QuickVoteStruct populated with all the
 102   # fields but the candidate ID's
 103   api_method :create_quickvote, :expects => [QuickVoteStruct],
 104              :returns => [:string]
 105 end