X-Git-Url: https://projects.mako.cc/source/selectricity/blobdiff_plain/49bc919b9f7edd189a311cdb910ab0a7500030ac..e8111bfbb23641eb8f5e6afadab6ec38e9e260c4:/app/apis/selectricity_api.rb?ds=inline diff --git a/app/apis/selectricity_api.rb b/app/apis/selectricity_api.rb index af75cf6..4878f5e 100644 --- a/app/apis/selectricity_api.rb +++ b/app/apis/selectricity_api.rb @@ -1,36 +1,105 @@ -class ElectionStruct < ActionWebService::Struct +# Selectricity: Voting Machinery for the Masses +# Copyright (C) 2007, 2008 Benjamin Mako Hill +# 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 +# . + +class QuickVoteStruct < ActionWebService::Struct member :name, :string member :description, :string - member :candidates, [:int] + member :candidate_ids, [:int] + member :candidate_names, [:string] member :id, :int end -class VoteInfo < ActionWebService::Struct + +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 VoteResultStruct < ActionWebService::Struct +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 => [:string, :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]] - api_method :get_quickvote_votes, :expects => [:string], :returns => [ [VoteInfo] ] - api_method :list_quickvotes, :expects => [], :returns => [[ElectionStruct]] -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