ranked-voting
Simple app for ranked-choice voting in an election.
Ranked-voting is a Flask app that serves API endpoints for a ranked-choice voting, supporting both creation of elections, retrieval of results and casting of votes using HTTP requests.
How to use ranked-voting
Create an Election
Creation of elections is performed by sending either a GET
or POST
request.
GET
A GET
request is the quickest way to setup a ranked-choice election, but offers no customization options since all fields take their default values. Create an election by appending a /
separated list of candidates to the /add
endpoint.
curl --location --request GET 'https://ranked-voter.herokuapp.com/add/pancakes/waffles/ice-cream'
POST
You can also create an election by sending a POST
request. This is the most flexible way to create an election, but requires you to specify the fields you wish to customize.
The request body is a JSON object with the following fields:
{
"election_id": {OPTIONAL} A custom ID for the election. If not provided, a random ID will be generated.
"election_name": {OPTIONAL} The name of your election
"start_time": {OPTIONAL} when does the election start?
"end_time": {OPTIONAL} when does the election end?
"description": {OPTIONAL} A short description of your election
"anonymous": {OPTIONAL} true or false
"candidates": ["candidate-1", "candidate-2", ...]
}
An example is provided below:
curl --location --request POST 'https://ranked-voter.herokuapp.com/add' \
--header 'Content-Type: application/json' \
--data-raw '{
"election_name": "Food ranking",
"description": "Rank your favourite foods!",
"candidates": ["pancakes", "ice-cream", "waffles"],
"anonymous": true
}'
Once you create an election, you will be shown the ELECTION_ID
. Remember to use this ID when casting your votes and to access results.
Retrieve Results
You can view your election results by sending a GET
request to the /ELECTION_ID
endpoint.
An example is provided below:
curl --location --request GET 'https://ranked-voter.herokuapp.com/ELECTION_ID'
Remove an Election
You can remove an election by sending a GET
request to the /vote/ELECTION_ID
endpoint. Note that this action is irreversible and can only be performed by the person who created the election.
curl --location --request GET 'https://ranked-voter.herokuapp.com/remove/ELECTION_ID'
Cast your votes
You can cast your votes by sending a GET
request to the vote/ELECTION_ID
endpoint. Append the URL with the ordered candidates, separated with a /
. Remember to include all the candidates since this is a ranked-choice voting.
An example is provided below:
curl --location --request GET 'https://ranked-voter.herokuapp.com/vote/ELECTION_ID/pancakes/icecream/waffles'
Remove your vote
You can remove your vote by sending a GET
request to the /unvote/ELECTION_ID
endpoint. Note that this action will remove only your vote, not all votes.
curl --location --request GET 'https://ranked-voter.herokuapp.com/unvote/ELECTION_ID'
How to setup ranked-voting
-
Clone the repository and navigate to the root directory
git clone https://github.com/aditeyabaral/ranked-voting cd ranked-voting
-
Create a new Python3 environment and activate it
virutalenv ranked-voting source ranked-voting/bin/activate
-
Install the requirements
pip install -r requirements.txt
-
Create a
.env
file and add a database connection URLAPP_DATABASE_URL="<YOUR-DATABASE-URL>"
-
Run the app
python3 app/app.py