{"id":26092883,"url":"https://github.com/election-tech-initiative/electionguard-api-python","last_synced_at":"2025-10-14T15:07:37.100Z","repository":{"id":43005287,"uuid":"221412144","full_name":"Election-Tech-Initiative/electionguard-api-python","owner":"Election-Tech-Initiative","description":"ElectionGuard Web API in python to demonstrate usage of electionguard-python in performing ballot encryption, casting, spoiling, and tallying.","archived":false,"fork":false,"pushed_at":"2023-08-02T21:11:37.000Z","size":35447,"stargazers_count":36,"open_issues_count":14,"forks_count":33,"subscribers_count":13,"default_branch":"main","last_synced_at":"2025-10-14T15:06:02.680Z","etag":null,"topics":["api","electionguard","fastapi","hacktoberfest","python"],"latest_commit_sha":null,"homepage":"https://www.electionguard.vote/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Election-Tech-Initiative.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-11-13T08:42:09.000Z","updated_at":"2025-04-13T19:10:05.000Z","dependencies_parsed_at":"2024-12-03T17:46:05.948Z","dependency_job_id":"3b1d5cd4-af7e-42ed-9be3-3c282c7e8ae1","html_url":"https://github.com/Election-Tech-Initiative/electionguard-api-python","commit_stats":null,"previous_names":["election-tech-initiative/electionguard-api-python","microsoft/electionguard-api-python"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/Election-Tech-Initiative/electionguard-api-python","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Election-Tech-Initiative%2Felectionguard-api-python","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Election-Tech-Initiative%2Felectionguard-api-python/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Election-Tech-Initiative%2Felectionguard-api-python/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Election-Tech-Initiative%2Felectionguard-api-python/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Election-Tech-Initiative","download_url":"https://codeload.github.com/Election-Tech-Initiative/electionguard-api-python/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Election-Tech-Initiative%2Felectionguard-api-python/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279019293,"owners_count":26086709,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-14T02:00:06.444Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","electionguard","fastapi","hacktoberfest","python"],"created_at":"2025-03-09T11:10:18.754Z","updated_at":"2025-10-14T15:07:37.067Z","avatar_url":"https://github.com/Election-Tech-Initiative.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Microsoft Defending Democracy Program: ElectionGuard](https://raw.githubusercontent.com/microsoft/electionguard-web-api/main/images/electionguard-banner.svg)\n\n# 🗳️ ElectionGuard Web API\n\n[![docker version](https://img.shields.io/docker/v/electionguard/electionguard-web-api)](https://hub.docker.com/r/electionguard/electionguard-web-api) [![docker pulls](https://img.shields.io/docker/pulls/electionguard/electionguard-web-api)](https://hub.docker.com/r/electionguard/electionguard-web-api) [![Language grade: Python](https://img.shields.io/lgtm/grade/python/g/microsoft/electionguard-web-api.svg?logo=lgtm\u0026logoWidth=18)](https://lgtm.com/projects/g/microsoft/electionguard-web-api/context:python) [![Total alerts](https://img.shields.io/lgtm/alerts/g/microsoft/electionguard-web-api.svg?logo=lgtm\u0026logoWidth=18)](https://lgtm.com/projects/g/microsoft/electionguard-web-api/alerts/) [![Documentation Status](https://readthedocs.org/projects/electionguard-web-api/badge/?version=latest)](https://electionguard-web-api.readthedocs.io) [![license](https://img.shields.io/github/license/microsoft/electionguard-web-api)](LICENSE)\n\nThe ElectionGuard Web API is a python-based application that provides a **thin**, **stateless** wrapper around the [`electionguard-python`](https://github.com/microsoft/electionguard-python) library to perform ballot encryption, casting, spoiling, and tallying. This API is implemented using [FastAPI](https://fastapi.tiangolo.com/#interactive-api-docs).\n\nIf you aren't familiar with ElectionGuard and its concepts, first take a stroll through [the official documentation](https://microsoft.github.io/electionguard-python/).\n\n## 👯‍♀️ Two APIs in One\n\nBefore you begin you should be aware that the application can run in one of two modes:\n\n- `guardian` mode runs features used by Guardians (key ceremony actions, partial tally decryption, etc.)\n- `mediator` mode runs features used by Mediators (ballot encryption, casting, spoiling, etc.)\n\nIn 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 as described below.\n\n## ⭐ Getting Started\n\nThis codebase can be run using one of three different approaches:\n\n1. 🐳 Running with Docker\n2. 🐳 Developing with Docker\n3. 🐍 Developing with Python\n\n## 🐳 1. Running with Docker\n\nThis approach runs an official published image. This approach is not intended for development. It works on Windows, Mac, and Linux.\n\nFor convenience the Docker image is hosted on both [Github Packages](https://github.com/microsoft/electionguard-web-api/packages/397920) and [DockerHub](https://hub.docker.com/r/electionguard/electionguard-web-api). You can choose whichever container image library works best for you.\n\n### 1.1 Pulling from Github Packages\n\n**Note:** _GitHub Packages requires authentication to retrieve the package. This requires a GitHub Access Token and using `docker login`. [Follow GitHub instructions](https://docs.github.com/en/packages/using-github-packages-with-your-projects-ecosystem/configuring-docker-for-use-with-github-packages#authenticating-with-a-personal-access-token)._\n\n```bash\n# Pull the image from Github\ndocker pull docker.pkg.github.com/microsoft/electionguard-web-api/electionguard-web-api:main\n\n# Start a container for the API in mediator mode, exposed on port 80 of the host machine\ndocker run -d -p 80:8000 --env API_MODE=mediator docker.pkg.github.com/microsoft/electionguard-web-api/electionguard-web-api:main\n```\n\n### 1.2 Pulling from DockerHub\n\nPulling from DockerHub is simpler as it requires no additional authentication.\n\n```bash\n# Pull the image from DockerHub\ndocker pull electionguard/electionguard-web-api:latest\n\n# Start a container for the API in mediator mode, exposed on port 80 of the host machine\ndocker run -d -p 80:8000 --env API_MODE=mediator electionguard/electionguard-web-api:latest\n```\n\n## 🐳 2. Developing with Docker\n\nDeveloping with Docker is the fastest approach for getting started because it has virtually no local dependencies (e.g. Python). This approach works on Windows, Mac, and Linux. It uses a [Dockerfile](Dockerfile) and [docker-compose.yml](docker-compose.yml).\n\n### ✅ 2.1 Prerequisities\n\n- [GNU Make](https://www.gnu.org/software/make/manual/make.html) is required to simplify commands and GitHub Actions. For MacOS and Linux, no action is necessary as it pre-installed. For Windows, install via [Chocolatey](https://chocolatey.org/install) and the [make package](https://chocolatey.org/packages/make), or alternately [manually install](http://gnuwin32.sourceforge.net/packages/make.htm).\n- [Docker Desktop](https://www.docker.com/products/docker-desktop) is required for Docker support\n\n### 🏃‍♀️ 2.2 Running 🏃‍♂️\n\nTo get started run both APIs at the same time:\n\n```bash\nmake docker-run\n```\n\nOr run both APIs in development mode, with automatic reloading on file change:\n\n```bash\nmake docker-dev\n```\n\nAfter 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\n\n## 🐍 3. Developing with Python\n\nDeveloping with Python provides the fastest developer inner loop (speed from code changes to seeing effects of changes), but is more work to set up initially. It works on Mac and Linux. It also works via [WSL 2](https://docs.microsoft.com/en-us/windows/wsl/about) on Windows.\n\n### ✅ 3.1. Windows Prerequisites\n\nOn Windows you can use an IDE of your choice in Windows, and run the make and Python commands in WSL which will expose API's in Windows. Developing with Python on Windows involves the following additional setup that is not required for Linux or Mac.\n\n1. Install [WSL 2](https://docs.microsoft.com/en-us/windows/wsl/install)\n2. Install [Ubuntu](https://www.microsoft.com/en-us/p/ubuntu/9nblggh4msv6?ocid=9nblggh4msv6_ORSEARCH_Bing\u0026rtc=1\u0026activetab=pivot:overviewtab) (other Linux distributions should also work with minor modifications to the instructions below)\n3. Install [pyenv prerequisites](https://github.com/pyenv/pyenv/wiki#suggested-build-environment). Technically you could just install Python and it would be simpler, but this approach will provide more flexibility. To install the prerequisites:\n\n```bash\nsudo apt-get update\nsudo apt-get install make build-essential libssl-dev zlib1g-dev \\\n  libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm \\\n  libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev\n```\n\n4. Install pyenv via [pyenv-installer](https://github.com/pyenv/pyenv-installer) and add it the startup scripts:\n\n```bash\ncurl https://pyenv.run | bash\necho 'export PYENV_ROOT=\"$HOME/.pyenv\"' \u003e\u003e ~/.bashrc\necho 'export PATH=\"$PYENV_ROOT/bin:$PATH\"' \u003e\u003e ~/.bashrc\necho -e 'if command -v pyenv 1\u003e/dev/null 2\u003e\u00261; then\\n eval \"$(pyenv init -)\"\\nfi' \u003e\u003e ~/.bashrc\nsed -Ei -e '/^([^#]|$)/ {a \\\n  export PYENV_ROOT=\"$HOME/.pyenv\"\n  a \\\n  export PATH=\"$PYENV_ROOT/bin:$PATH\"\n  a \\\n  ' -e ':a' -e '$!{n;ba};}' ~/.profile\necho 'eval \"$(pyenv init --path)\"' \u003e\u003e~/.profile\n\necho 'eval \"$(pyenv init -)\"' \u003e\u003e ~/.bashrc\n```\n\n5. Restart shell\n6. Install Python 3.9 via pyenv\n\n```bash\npyenv install 3.9.9\npyenv global 3.9.9\n```\n\n### ✅ 3.2 Mac/Linux Prerequisites\n\nInstall [Python 3.9](https://www.python.org/downloads/). We additionally recommend [pyenv](https://github.com/pyenv/pyenv) to assist with Python version management (see detailed instructions in the Windows section above starting with Step 3).\n\n### 🏃‍♀️ 3.2 Running 🏃‍♂️\n\nUsing [**make**](https://www.gnu.org/software/make/manual/make.html), install and setup the environment:\n\n```bash\nmake environment\n```\n\nStart the api as mediator\n\n```bash\nmake start API_MODE=mediator\n```\n\nOR as guardian\n\n```bash\nmake start API_MODE=guardian\n```\n\n### Debugging Mac/Linux\n\nFor 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.\n\nIf the code fails to run, [make sure your Python interpreter is set](https://code.visualstudio.com/docs/python/environments) to use your poetry environment.\n\n### Debugging Windows\n\nWith Visual Studio Code:\n\n1. Install the [Remote WSL](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-wsl) extension\n2. In the bottom left click the Green Icon and \"New WSL Window using Distro\", select Ubuntu\n3. F5\n4. Choose either `Guardian Web API` or `Mediator Web API`\n\n## 🧪 Testing\n\nEnd-to-end integration tests can be found in the [`/tests/integration`](/tests/integration) folder. To see them in action, run:\n\n```bash\nmake test-integration\n```\n\nA Postman collection is also available to test the API located in the [`/tests/postman`](/tests/postman) folder. You can do a few things with this:\n\n- [Import into Postman](https://learning.postman.com/docs/getting-started/importing-and-exporting-data/#importing-data-into-postman) for easy manual testing.\n- Run locally with the [Newman CLI](https://github.com/postmanlabs/newman).\n- Run the APIs and tests entirely in Docker by running:\n  ```bash\n  make docker-postman-test\n  ```\n\n## 📝 Documentation\n\n**FastApi** defaultly has API documentation built in. The following is available after running:\n\n- **[SwaggerUI](https://github.com/swagger-api/swagger-ui)** at [`http://127.0.0.1:8000/docs`](http://127.0.0.1:8000/docs) or [`http://127.0.0.1:8001/docs`](http://127.0.0.1:8001/docs), depending on the API mode\n\n- **[ReDoc](https://github.com/Redocly/redoc)** at [`http://127.0.0.1:8000/redoc`](http://127.0.0.1:8000/redoc) or [`http://127.0.0.1:8001/redoc`](http://127.0.0.1:8001/redoc)\n\nOverviews of the API itself are available on:\n\n- [GitHub Pages](https://microsoft.github.io/electionguard-web-api/)\n- [Read the Docs](https://electionguard-web-api.readthedocs.io/)\n\n## 🗄 Archived\n\nAs of 06/15/2020, the previous C wrapped implementation was transitioned to the python version. ElectionGuard development has transitioned to the [ElectionGuard-Python](https://github.com/microsoft/electionguard-python) Repo. The old version is available using the `dotnet-api` tag.\n\n## 🤝 Contributing\n\nThis 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.md)\n\n### Code of Conduct\n\nThis project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.\n\n### Reporting Issues\n\nPlease report any bugs, feature requests, or enhancements using the [GitHub Issue Tracker](https://github.com/microsoft/electionguard-web-api/issues). 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](https://msrc.microsoft.com/create-report). See the [Security Documentation](SECURITY.md) for more information.\n\n### Have Questions?\n\nElectionguard 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.\n\n## License\n\nThis repository is licensed under the [MIT License](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felection-tech-initiative%2Felectionguard-api-python","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Felection-tech-initiative%2Felectionguard-api-python","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felection-tech-initiative%2Felectionguard-api-python/lists"}