Charts API app

This sample Python Flask application builds a Charts API by using APIFlask with matplotlib to return charts as PNG images. You can use this project as a starting point for your own Flask APIs.

The repository is designed for use with Docker containers, both for local development and deployment, and includes infrastructure files for deployment to Azure Container Apps. 🐳

The code is tested with pytest and schemathesis, linted with ruff, and formatted with black. Code quality issues are all checked with both pre-commit and Github actions.

Opening the project

This project has Dev Container support, so it will be be setup automatically if you open it in Github Codespaces or in local VS Code with the Dev Containers extension.

If you're not using one of those options for opening the project, then you'll need to:

1. Create a Python virtual environment and activate it.

2. Install the requirements:

   python3 -m pip install -r requirements-dev.txt

3. Install the pre-commit hooks:

   pre-commit install

Local development

1. Run the local server:

   python3 -m flask --debug --app src/api:app run --port 50505

2. Click 'http://127.0.0.1:50505' in the terminal, which should open a new tab in the browser.

3. Open the API specification at /openapi.json

4. Try the API at these sample URLs:

   charts/bar?title=Enrolled%20students&xlabel=Courses%20offered&ylabel=Number%20enrolled&xvalues=C,Ruby,Java,Python&yvalues=10,20,15,30.5

   charts/pie?title=Enrolled%20students&xlabel=Courses%20offered&ylabel=Number%20enrolled&labels=C,Ruby,Java,Python&values=10,20,15,30.5

Local development with Docker

You can also run this app locally with Docker, thanks to the Dockerfile. You need to either have Docker Desktop installed or have this open in Github Codespaces for these commands to work.

1. Install Docker Desktop. If you opened this inside Github Codespaces or a Dev Container in VS Code, installation is not needed. ⚠️ If you're on an Apple M1/M2, you won't be able to run docker commands inside a Dev Container; either use Codespaces or do not open the Dev Container.

2. Build the image:

   docker build --tag flask-api src/

3. Run the image:

   docker run --publish 50505:50505 flask-api

4. Follow instructions above to test the API is working.

Running tests

This project uses pytest for testing and coverage for test coverage. Both are configured in pyproject.toml.

Run the unit tests:

python3 -m pytest

This project also uses schemathesis to run property-based tests based on the generated OpenAPI schema.

Run property-based tests:

python3 -m pytest src/tests/property_based.py

Both commands are also run as part of the CI/CD pipeline. If test coverage falls below 100%, the pipeline will fail.

Deployment

This repo is set up for deployment on Azure Container Apps using the configuration files in the infra folder.

This diagram shows the architecture of the deployment:

Steps for deployment:

1. Sign up for a free Azure account and create an Azure Subscription.

2. Install the Azure Developer CLI. (If you open this repository in Codespaces or with the VS Code Dev Containers extension, that part will be done for you.)

3. Login to Azure:

   azd auth login

4. Provision and deploy all the resources:

   azd up

   It will prompt you to provide an azd environment name (like "flaskapi"), select a subscription from your Azure account, and select a location (like "eastus"). Then it will provision the resources in your account and deploy the latest code. If you get an error with deployment, changing the location can help, as there may be availability constraints for some of the resources.

5. When azd has finished deploying, you'll see an endpoint URI in the command output. Visit that URI and append charts/bar?xvalues=C,Ruby,Java,Python&yvalues=10,20,15,30.5 to see a bar chart PNG.

6. When you've made any changes to the app code, you can just run:

   azd deploy

CI/CD pipeline

This project includes a Github workflow for deploying the resources to Azure on every push to main. That workflow requires several Azure-related authentication secrets to be stored as Github action secrets. To set that up, run:

azd pipeline config

Costs

Pricing varies per region and usage, so it isn't possible to predict exact costs for your usage. The majority of the Azure resources used in this infrastructure are on usage-based pricing tiers. However, Azure Container Registry has a fixed cost per registry per day.

You can try the Azure pricing calculator for the resources:

• Azure Container App: Consumption tier with 0.5 CPU, 1GiB memory/storage. Pricing is based on resource allocation, and each month allows for a certain amount of free usage. Pricing
• Azure Container Registry: Basic tier. Pricing
• Azure CDN: Standard tier. Pricing
• Log analytics: Pay-as-you-go tier. Costs based on data ingested. Pricing

⚠️ To avoid unnecessary costs, remember to take down your app if it's no longer in use, either by deleting the resource group in the Portal or running azd down.

Getting help

If you're working with this project and running into issues, please post in Discussions.