๐ณ๏ธ ElectionGuard Web API
This is a python API that utilizes electionguard-python
to perform ballot encryption, casting, spoiling, and tallying. This API is implemented using FastAPI.
๐ฏโโ๏ธ Two APIs in One
The application can run in one of two modes:
guardian
mode runs features used by Guardians (key ceremony actions, partial tally decryption, etc.)mediator
mode runs features used by Mediators (ballot encryption, casting, spoiling, etc.)
In practice, you will likely need to run at least one instance of each mode. We provide a single codebase and Docker image, but the mode can be set at runtime.
๐ณ Running with Docker
If you run Docker and want to get started quickly, we provide a Dockerfile and docker-compose.yml.
Run both APIs at the same time:
make docker-run
Or run both APIs in development mode, with automatic reloading on file change:
make docker-dev
After either command, you will find the mediator
API running at http://127.0.0.1:8000 and the guardian
API at http://127.0.0.1:8001
๐ Running with Python
Requirements
These requirements line up with electionguard-python.
- Python 3.8 is required to develop this API. If developer uses multiple versions of python, pyenv is suggested to assist version management.
- GNU Make is used to simplify the commands and GitHub Actions. This approach is recommended to simplify the command line experience. This is built in for MacOS and Linux. For Windows, setup is simpler with Chocolatey and installing the provided make package. The other Windows option is manually installing make.
- pipenv is used to configure the python environment. Installation instructions can be found here.
Quick Start
Using make, installation and startup can be run with one command:
To set up the environment:
make environment
To start the api:
make start API_MODE=mediator
OR
make start API_MODE=guardian
Debugging
For local debugging with Visual Studio Code, choose the Guardian Web API
or Mediator Web API
options from the dropdown in the Run menu. Once the server is up, you can easily hit your breakpoints.
If the code fails to run, make sure your Python interpreter is set to use your pipenv environment.
๐งช Testing
A Postman collection is available to test the API located in the /tests
folder. This can be imported into Postman for easy testing. This suite works on a local run server or the preconfigured docker settings.
๐ Documentation
FastApi defaultly has API documentation built in. The following is available after running:
-
SwaggerUI at
http://127.0.0.1:8000/docs
orhttp://127.0.0.1:8001/docs
, depending on the API mode -
ReDoc at
http://127.0.0.1:8000/redoc
orhttp://127.0.0.1:8001/redoc
Overviews of the API itself are available on:
๐ Archived
As of 06/15/2020, the previous C wrapped implementation was transitioned to the python version. ElectionGuard development has transitioned to the ElectionGuard-Python Repo. The old version is available using the dotnet-api
tag.
๐ค Contributing
This project encourages community contributions for development, testing, documentation, code review, and performance analysis, etc. For more information on how to contribute, see [the contribution guidelines][contributing]
Code of Conduct
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.
Reporting Issues
Please report any bugs, feature requests, or enhancements using the GitHub Issue Tracker. Please do not report any security vulnerabilities using the Issue Tracker. Instead, please report them to the Microsoft Security Response Center (MSRC) at https://msrc.microsoft.com/create-report. See the [Security Documentation][security] for more information.
Have Questions?
Electionguard would love for you to ask questions out in the open using GitHub Issues. If you really want to email the ElectionGuard team, reach out at electionguard@microsoft.com.
License
This repository is licensed under the [MIT License]