An open delegative voting API

So democratic decision making platforms can easily apply liquid democracy principles.

You can test-drive the live API by pointing a GraphiQL app at https://api.liquidvoting.io, then adding the demo auth key to the authorization header:

{ "Authorization": "Bearer 62309201-d2f0-407f-875b-9f836f94f2ca" }

And running the following sample queries. If you prefer trying it with curl, there are examples below the pure GraphQL queries.

There’s also a ruby client in the works.

Delegating a vote for a proposal

Bob delegates voting to Alice, on a proposal made through a Github pull request. Proposals can be any content accessible through a url.

GraphQL query

mutation {
  createDelegation(proposalUrl: "https://github.com/user/repo/pulls/15", delegatorEmail: "bob@example.com", delegateEmail: "alice@example.com") {
    delegator {
      email
    }
    delegate {
      email
    }
    proposalUrl
  }
}

Curl request

curl -X POST https://api.liquidvoting.io \
-H "Content-Type: application/json" \
-H "Authorization: Bearer 62309201-d2f0-407f-875b-9f836f94f2ca" \
-d '{ "query": "mutation { createDelegation(proposalUrl: \"https://github.com/user/repo/pulls/15\", delegatorEmail: \"bob@example.com\", delegateEmail: \"alice@example.com\") { delegator { email } delegate { email } proposalUrl }}" }'

=> {"data":{"createDelegation":{"delegate":{"email":"alice@example.com"},"delegator":{"email":"bob@example.com"},"proposalUrl":"https://github.com/user/repo/pulls/15"}}}

Voting for a proposal and getting a voting result back

Alice votes on pull request carrying Bob’s vote with her.

Voting result comes back on the same response.

GraphQL query

mutation {
  createVote(participantEmail: "alice@example.com", proposalUrl:"https://github.com/user/repo/pulls/15", yes: true) {
    participant {
      email
    }
    yes
    votingResult {
      inFavor
      against
    }
  }
}

Curl request

curl -X POST https://api.liquidvoting.io \
-H "Content-Type: application/json" \
-H "Authorization: Bearer 62309201-d2f0-407f-875b-9f836f94f2ca" \
-d '{ "query": "mutation { createVote(participantEmail: \"alice@example.com\", proposalUrl:\"https://github.com/user/repo/pulls/15\", yes: true) { participant { email } yes votingResult { inFavor against } } }" }'

=> {"data":{"createVote":{"participant":{"email":"alice@example.com"},"votingResult":{"inFavor":2,"against":0,"proposalUrl":"https://github.com/user/repo/pulls/15"},"yes":true}}}

Note that votingResult["inFavor"] => 2, because the vote has a weight of 2 due to the delegation given to Alice.

It’s open source

The code is available on Github under the MIT license.

You can follow the project backlog here.

There is a docker image available as well. Here’s how to run the container locally:

docker run -it --rm \
  -e SECRET_KEY_BASE=$(mix phx.gen.secret) \
  -e DB_USERNAME=postgres \
  -e DB_PASSWORD=postgres \
  -e DB_NAME=liquid_voting_dev \
  -e DB_HOST=host.docker.internal \
  -p 4000:4000 \
  docker.pkg.github.com/liquidvotingio/api/api:latest

Contributors are welcome!