projects.mako.cc - selectricity-live/blob - old_api_code/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. Please see the COPYING file for
   6 # details.
   7
   8 class QuickVoteStruct < ActionWebService::Struct
   9   member :name, :string
  10   member :description, :string
  11   member :candidate_ids, [:int]
  12   member :candidate_names, [:string]
  13   member :id, :int
  14 end
  15
  16 class QuickVoterInfo < ActionWebService::Struct
  17   member :voter_id, :int
  18   member :voter_session_id, :string
  19   member :voter_ipaddress, :string
  20   member :vote_time, :int
  21   member :vote, [:int]
  22 end
  23
  24 class QuickVoteResultStruct < ActionWebService::Struct
  25   member :plurality_winners, [:int]
  26   member :approval_winners, [:int]
  27   member :condorcet_winners, [:int]
  28   member :ssd_winners, [:int]
  29   member :borda_winners, [:int]
  30 end
  31
  32
  33 class QuickVoteCandidateMap < ActionWebService::Struct
  34   member :candidate_ids, [:int]
  35   member :candidate_names, [:string]
  36 end
  37
  38
  39 # An API for interfacing with Selectricity
  40 # This allows for things like XML-RPC to have a unified interface
  41 # The implementation is elsewhere.
  42
  43 class SelectricityAPI < ActionWebService::API::Base
  44
  45   # Casts a quickvote.  Expects a quickvote name, a voter ID, and a list
  46   # of candidate ID's respectively.  Returns a string containing any
  47   # potential errors that occurred in the process.
  48   api_method :cast_quickvote, :expects => [:string, :int, [[:int]]],
  49              :returns => [:string]
  50
  51   # Return the results of a QuickVote.  Takes in the name of a
  52   # quickvote, and returns a structure as described by
  53   # QuickVoteResultStruct
  54
  55   api_method :get_quickvote_results, :expects => [:string],
  56              :returns => [QuickVoteResultStruct]
  57
  58   # Returns information regarding all the candidates in a QuickVote
  59   # Takes in a QuickVote name, and returns the list of names and ID's of
  60   # candidates This can be useful for presenting the user with a list of
  61   # readable names, while the software sends results to us in the
  62   # numeric ID's we require. The two lists are in respective order.
  63
  64   api_method :get_quickvote_candidate_map, :expects => [:string],
  65              :returns => [QuickVoteCandidateMap]
  66
  67   # Converts QuickVote candidate ID's to names Takes in a QuickVote name
  68   # and a list of candidate ID's, and returns the names of each
  69   # candidate. Useful for doing just a few lookups; it's more efficient
  70   # to use get_quickvote_candidate_map for presenting info about an
  71   # entire election.
  72
  73   api_method :quickvote_candidate_ids_to_names,
  74              :expects => [:string,[:int]], :returns => [[:string]]
  75
  76   # Get information on all the votes cast in a QuickVote Takes in the
  77   # name of a QuickVote, returns an array of QuickVoterInfo structures.
  78   api_method :get_quickvote_votes, :expects => [:string],
  79              :returns => [ [QuickVoterInfo] ]
  80
  81   # Gets a list of all QuickVotes in the system.
  82   api_method :list_quickvotes, :expects => [],
  83              :returns => [[QuickVoteStruct]]
  84
  85   # Gets information on a particular QuickVote.  Takes in a QuickVote
  86   # name.
  87   api_method :get_quickvote, :expects => [:string],
  88              :returns => [QuickVoteStruct]
  89
  90   # Create a QuickVote Pass in a QuickVoteStruct populated with all the
  91   # fields but the candidate ID's
  92   api_method :create_quickvote, :expects => [QuickVoteStruct],
  93              :returns => [:string]
  94 end