Skip to content

Latest commit

 

History

History
424 lines (286 loc) · 9.57 KB

API.md

File metadata and controls

424 lines (286 loc) · 9.57 KB

Authentication

POST /api/login

Creates a session cookie to authenticate user
Valid for 59 minutes because the token generated by firebase is valid for 60 minutes

Request JSON

{
 idToken - the idToken generated by firebase on authentication from client side
}

Response

  • Status code: 200
    • JSON returned:
      {
       isOrganizer: true if the user is an organizer otherwise false,
      }
  • Status code: 401
    • Return: "Unauthorized"

GET /api/logout

Clear session cookies

Request JSON

  • No parameters

Response

  • No return

POST /api/register

  • Register a new user

Request JSON

{
 name: name of user,
 email: email address of user,
 password: password of user,
 isOrganizer: true if the new user is an organizer, otherwise false
}

Response

  • Status code: 200
    • Return: "User successfully registered"
  • Status code: 400
    • Return: "bad request"

Organizer

POST /api/election/create

Store the data of new election in database

Request JSON

{
 candidates: array of candidates,
 startTime: start time of election in UTC time,
 endTime: end time of election in UTC time,
 validVoters: array of voter IDs that are to be validated,
 electionName: name of the election,
}

Response

  • Status code: 200
    • JSON returned:
      {
       electionID: "ID of the election generated by firebase"
      }
  • Status code: 401
    • Return: "Unauthorized"
  • Status code: 400
    • Return: "bad request"

PUT /api/election/{electionID}/deploy

Deploys the election contract and validates voters

URL parameter

  • electionID: election ID of the election whose contract has to be deployed

Request JSON

  • EMPTY

Response

  • Status code: 200

    • JSON returned:
      {
       electionID: ID of the election,
       electionAddress: Address of the contract on the blockchain,
       invalidVoterIDs: array of voter IDs that failed to be validated
      }

  • Status code: 206

    • Indicates that the election has already been deployed
    • JSON returned:
      {
       electionAddress: "Address of the contract"
      }

  • Status code: 401

    • Return: "Unauthorized"

  • Status code: 400

    • Return: "bad request"

PUT /api/election/{electionID}/validate

validate the list of voter IDs

URL Paramter

  • electionID: election ID of the corresponding election

Request JSON

{
 validVoters: array of voter IDs that are to be validated
}

Response

  • Status code: 200

    • JSON returned:
      {
       invalidVoterIDs: array of voter IDs that failed to be validated,
      }

  • Status code: 401

    • Return: "Unauthorized"

  • Status code: 400

    • Return: "bad request"

GET /api/election/

gets all the elections that this organizer which are either ongoing, upcoming or previous.
any election that hasn't been deployed will be part of upcoming election irrespective of that election's start or end time.

Request JSON

  • {time: "ongoing" OR "previous" OR "upcoming"}
  • choose only one of the above options for time

Response

  • Status code: 200

    • JSON returned:
      {
       "ELECTION ID": {
        candidates: array of candidates,
        endTime: end time of election in UTC in ISO format,
        startTime: start time of election in UTC is ISO format,
        electionName: name of election,
        organizerName: name of organizer,
        organizerID: ID of the organizer,
         validVoters: list of valid voters,
         address: address of deployed contract
        }
      }
      • Note the "ELECTION ID" is actually the alphanumeric ID of an election and not literally the words "ELECTION ID".
      • So this JSON will contain objectes whose keys are the ELECTION ID of the organizer's election and each ELECTION ID will contain the fields mentioned above.
      • The address field will exist only if the contract has been deployed

  • Status code: 401

    • Return: "Unauthorized"

  • Status code: 400

    • Return: "bad request"

GET /api/election/{electionID}

Get the details of a particular election

URL parameter

  • electionID: ID of the election

Request JSON

  • EMPTY

Response

  • Status code: 200

    • JSON returned:
      {
       candidates: array of candidates,
       endTime: end time of election in UTC in ISO format,
       startTime: start time of election in UTC is ISO format,
       electionName: name of election,
       organizerName: name of organizer,
       organizerID: ID of the organizer,
        validVoters: list of valid voters,
        address: address of deployed contract
      }
      • The address field will exist only if the contract has been deployed

  • Status code: 401

    • Return: "Unauthorized"

  • Status code: 400

    • Return: "bad request"

Voter

PUT /api/election/{electionID}/vote

End point to caste the vote

URL paramters

  • electionID: ID of the election in which the vote is to be casted

Request JSON

{
 candidateID: index of the candidate to be voted for }

  • candidates are indexed like an array starting from 0

Response

  • Status code: 200

    • JSON returned:
      {
       transaction hash: hash of the transaction that occurs on the blockchain when the vote is casted
      }

  • Status code: 401

    • Return: "Unauthorized"

  • Status code: 400

    • Return: One of the following will be returned:
      • "bad request"
      • "Not a valid voter"
      • "Vote has already been cast"

GET /api/election/

Gets the elections for which the voter is valid for. These elections are divided into previous, upcoming and ongoing elections

Request JSON

  • {time: "ongoing" OR "previous" OR "upcoming"}
  • choose only one of the above options for time

Response

  • Status code: 200

    • JSON returned:
      {
       "ELECTION ID": {
        candidates: array of candidates,
        endTime: end time of election in UTC in ISO format,
        startTime: start time of election in UTC is ISO format,
        electionName: name of election,
        organizerName: name of organizer,
         address: address of deployed contract
        }
      }

      • "ELECTION ID" is the alphanumeric ID of the election and not the words literally
      • The address field exists only if the contract has been deployed

  • Status code: 401

    • Return: "Unauthorized"

  • Status code: 400

    • Return: "bad request"

GET /api/election/{electionID}

Gets the election data for the election corresponding to {electionID}
Also tells whether the voter has voted or not and if they have then whom have they voted for

URL parameter

  • electionID: the ID of the election whose data is needed

Request JSON

  • EMPTY

Response

  • Status code: 200

    • JSON returned:
      {
       voted: true/false,
       votedFor: index of the candidate for whom they voted for,
       candidates: array of candidates,
       endTime: end time of election in UTC in ISO format,
       startTime: start time of election in UTC is ISO format,
       electionName: name of election,
       organizerName: name of organizer,
       address: address of deployed contract
      }
      • if voted is false then votedFor field won't exist

  • Status code: 401

    • Return: "Unauthorized"

  • Status code: 400

    • Return: "bad request"

GET /api/user/info

Gets the users name, email, userID, and their account type

URL parameter

  • None

Request JSON

  • EMPTY

Response

  • Status code: 200

    • JSON returned:
      {
       name: user’s name,
       email: user’s email,
       userID: users ID hash,
       accountType: “Organizer” or “voter”,
      }
      • if voted is false then votedFor field won't exist

  • Status code: 400

    • Return: "bad request"

GET /api/election/{electionID}/results

Returns an object with the results of the election

URL parameter

  • electionID: election ID of the election whose contract has to be updated

Request JSON

  • EMPTY

Response

  • Status code: 200

    • Return: {  "totalVotes": total number of votes casted,  "winner": the name of a candidate,  "results": an array of objects where each object contains the candidates name and vote count  {   "name": name of the candidate   "votes": the number of votes the candidate has  } }

  • Status code: 401

    • Return: "Unauthorized"

  • Status code: 400

    • Return: "bad request"

GET /api/election/{electionID}/update

Updates the election contract

URL parameter

  • electionID: election ID of the election whose contract has to be updated

Request JSON

  • Request JSON:
    {
     candidates: array of candidates,
     endTime: end time of election in UTC in ISO format,
     startTime: start time of election in UTC is ISO format,
     electionName: name of election,
     organizerName: name of organizer,
    }

Response

  • Status code: 200

    • Return: {  electionID: the elections ID }

  • Status code: 401

    • Return: "Unauthorized"

  • Status code: 400

    • Return: "bad request"