GIVE USPS Address Validation Microservice

The USPS microservice is a Python FastAPI application that exposes an API for address verification functions to GIVE via the USPS AII API.

Why this project

The GIVE USPS microservice aims to provide address verification capabilites to the GIVE API via its upstream USPS integration. The USPS microservice has the following goals:

• Expose the USPS address verification endpoints to GIVE users

CI/CD Workflows with GitHub Actions

The most up-to-date information about the CI/CD flows for this repo can be found in the GitHub workflows directory

Building Locally

Pre-requisites

Make sure you have the following installed if you intend to build the project locally.

• Python 3 (Check runtime.txt for exact version)
• CloudFoundry CLI

Development Setup

To set up your environment, run the following commands (or the equivalent commands if not using a bash-like terminal):

# Clone the project
git clone https://github.com/18F/identity-give-usps
cd identity-give-usps

# Set up Python virtual environment
python3.9 -m venv .venv
source venv/bin/activate
# .venv\Scripts\Activate.ps1 on Windows

# Install dependencies and pre-commit hooks
python -m pip install -r requirements-dev.txt
pre-commit install

Running the application

After completing development setup application locally with:

python -m pytest # NOTE that without DEBUG=True, local unit tests will fail
uvicorn usps.main:app

Viewing API Endpoints and documentation

Documentation can be viewed locally by running the application and visiting http://127.0.0.1:8000/redoc

Deploying to Cloud.gov during development

All deployments require having the correct Cloud.gov credentials in place. If you haven't already, visit Cloud.gov and set up your account and CLI.

manifest.yml file contains the deployment configuration for cloud.gov, and expects a vars.yaml file that includes runtime variables referenced. For info, see cloud foundry manifest files reference

Running the following cf command will deploy the application to cloud.gov

cf push --vars-file vars.yaml \
  --var ROUTE=<application-route> \
  --var TRANSACTION_ROUTE=<transaction-logging-service-route> \
  --var USPS_SERVICE_INFO=<usps-service-info> \
  --var USPS_TARGET_AUDIENCE=<usps-target-audience> \

Public domain

This project is in the worldwide public domain. As stated in CONTRIBUTING:

This project is in the public domain within the United States, and copyright and related rights in the work worldwide are waived through the CC0 1.0 Universal public domain dedication.

All contributions to this project will be released under the CC0 dedication. By submitting a pull request, you are agreeing to comply with this waiver of copyright interest.