Embeddable elctions now scale based on how many candidates in the election there...

[selectricity-live] / app / apis / selectricity_api.rb

diff --git a/app/apis/selectricity_api.rb b/app/apis/selectricity_api.rb
index da2f6f725f3a1698b2fb9ad42f7dbc752ac706fe..4878f5e54b707d7b671d99fb4a0160759a5ff662 100644 (file)
--- a/app/apis/selectricity_api.rb
+++ b/app/apis/selectricity_api.rb
@@ -1,21 +1,105 @@
-class VoteResultStruct < ActionWebService::Struct
+# Selectricity: Voting Machinery for the Masses
+# Copyright (C) 2007, 2008 Benjamin Mako Hill <mako@atdot.cc>
+# Copyright (C) 2007 Massachusetts Institute of Technology
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as
+# published by the Free Software Foundation, either version 3 of the
+# License, or (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public
+# License along with this program.  If not, see
+# <http://www.gnu.org/licenses/>.
+
+class QuickVoteStruct < ActionWebService::Struct
+  member :name, :string
+  member :description, :string
+  member :candidate_ids, [:int]
+  member :candidate_names, [:string]
+  member :id, :int
+end
+
+class QuickVoterInfo < ActionWebService::Struct
+  member :voter_id, :int
+  member :voter_session_id, :string
+  member :voter_ipaddress, :string
+  member :vote_time, :int
+  member :vote, [:int]
+end
+
+class QuickVoteResultStruct < ActionWebService::Struct
   member :plurality_winners, [:int]
   member :approval_winners, [:int]
   member :condorcet_winners, [:int]
   member :ssd_winners, [:int]
   member :borda_winners, [:int]
-  member :errors, [:string]
 end
-class CandidateMap < ActionWebService::Struct
+
+
+class QuickVoteCandidateMap < ActionWebService::Struct
   member :candidate_ids, [:int]
   member :candidate_names, [:string]
-  member :errors, [:string]
 end
+
+
+# An API for interfacing with Selectricity
+# This allows for things like XML-RPC to have a unified interface
+# The implementation is elsewhere.
+
 class SelectricityAPI < ActionWebService::API::Base
-  api_method :cast_quickvote, :expects => [:int, :int, [[:int]]], :returns => [:string]
-  api_method :get_quickvote_results, :expects => [:string], :returns => [VoteResultStruct]
-  api_method :get_quickvote_candidate_map, :expects => [:string], :returns => [CandidateMap]
-  api_method :quickvote_candidate_ids_to_names, :expects => [:string,[:int]], :returns => [[:string]]
-end
 
+  # Casts a quickvote.  Expects a quickvote name, a voter ID, and a list
+  # of candidate ID's respectively.  Returns a string containing any
+  # potential errors that occurred in the process.
+  api_method :cast_quickvote, :expects => [:string, :int, [[:int]]],
+             :returns => [:string]
+  
+  # Return the results of a QuickVote.  Takes in the name of a
+  # quickvote, and returns a structure as described by
+  # QuickVoteResultStruct
+  
+  api_method :get_quickvote_results, :expects => [:string],
+             :returns => [QuickVoteResultStruct]
+
+  # Returns information regarding all the candidates in a QuickVote
+  # Takes in a QuickVote name, and returns the list of names and ID's of
+  # candidates This can be useful for presenting the user with a list of
+  # readable names, while the software sends results to us in the
+  # numeric ID's we require. The two lists are in respective order.
+
+  api_method :get_quickvote_candidate_map, :expects => [:string],
+             :returns => [QuickVoteCandidateMap]
 
+  # Converts QuickVote candidate ID's to names Takes in a QuickVote name
+  # and a list of candidate ID's, and returns the names of each
+  # candidate. Useful for doing just a few lookups; it's more efficient
+  # to use get_quickvote_candidate_map for presenting info about an
+  # entire election.
+  
+  api_method :quickvote_candidate_ids_to_names,
+             :expects => [:string,[:int]], :returns => [[:string]]
+
+  # Get information on all the votes cast in a QuickVote Takes in the
+  # name of a QuickVote, returns an array of QuickVoterInfo structures.
+  api_method :get_quickvote_votes, :expects => [:string],
+             :returns => [ [QuickVoterInfo] ]
+  
+  # Gets a list of all QuickVotes in the system.
+  api_method :list_quickvotes, :expects => [],
+             :returns => [[QuickVoteStruct]]
+
+  # Gets information on a particular QuickVote.  Takes in a QuickVote
+  # name.
+  api_method :get_quickvote, :expects => [:string],
+             :returns => [QuickVoteStruct]
+
+  # Create a QuickVote Pass in a QuickVoteStruct populated with all the
+  # fields but the candidate ID's
+  api_method :create_quickvote, :expects => [QuickVoteStruct],
+             :returns => [:string]
+end