Feature/beautify (#20)

Author: simonkurtz-MSFT

README.md

@@ -6,7 +6,7 @@ This repository provides a playground to safely experiment with and learn Azure
 
 _If you are interested in APIM & Azure OpenAI integrations, please check out the excellent [AI Gateway](https://github.com/Azure-Samples/AI-Gateway) GitHub repository._
 
-## Objectives
+## 🎯 Objectives
 
 1. Educate you on common APIM architectures we see across industries and customers.
 1. Empower you to safely experiment with APIM policies.
@@ -16,9 +16,9 @@ _Try it out, learn from it, apply it in your setups._
 
 ---
 
-## Getting Started
+## 🚀 Getting Started
 
-### Prerequisites
+### 📋 Prerequisites
 
 These prerequisites apply broadly across all infrastructure and samples. If there are specific deviations, expect them to be noted there.
 
@@ -29,7 +29,7 @@ These prerequisites apply broadly across all infrastructure and samples. If ther
 - [An Azure Subscription](https://azure.microsoft.com/free/) with Owner or Contributor+UserAccessAdministrator permissions. Execute [shared/jupyter/verify-az-account.ipynb](shared/jupyter/verify-az-account.ipynb) to verify.
 - [Sign in to Azure with Azure CLI](https://learn.microsoft.com/cli/azure/authenticate-azure-cli-interactively)
 
-### Initialization
+### 🛠️ Initialization
 
 Run through the following steps to create a Python virtual environment before doing anything else:
 
@@ -43,15 +43,15 @@ Run through the following steps to create a Python virtual environment before do
 
 The first time you run a Jupyter notebook, you'll be asked to install the Jupyter kernel package (ipykernel).
 
-### List of Samples
+### 📁 List of Samples
 
 | Sample Name | Description | Supported Infrastructure(s) |
 |:-----------------|:----------------------------------------------------------------------------|:-------------------------------------------|
 | [General](./samples/general/create.ipynb) | Basic demo of APIM sample setup and policy usage. | All infrastructures |
 | [Load Balancing](./samples/load-balancing/create.ipynb) | Priority and weighted load balancing across backends. | apim-aca, afd-apim (with ACA) |
 | [AuthX](./samples/authx/create.ipynb) | Authentication and role-based authorization in a mock HR API. | All infrastructures |
 
-### Running a Sample
+### ▶️ Running a Sample
 
 1. Locate the specific sample's `create.ipynb` file and adjust the parameters under the `User-defined Parameters` header as you see fit.
 1. Ensure that the specified infrastructure already exists in your subscription. If not, proceed to the desired infrastructure folder and execute its `create.ipynb` file. Wait until this completes before continuing.
@@ -61,9 +61,9 @@ Now that infrastructure and sample have been stood up, you can experiment with t
 
 ---
 
-## Repo Structure
+## 📂 Repo Structure
 
-### High-level 
+### 🦅 High-level
 
 - All _samples_ can be found in the `samples` folder. Samples showcase functionality and provide a baseline for your experimentation.
 - All _infrastructures_ can be found in the `infrastructure` folder. They provide the architectural underpinnings.
@@ -73,14 +73,14 @@ Now that infrastructure and sample have been stood up, you can experiment with t
   - Reusable _APIM policies_ are found in the `apim-policies` folder. 
   - Reusable Jupyter notebooks are found in the `jupyter` folder.
 
-### Sample Setup
+### ⚙️ Sample Setup
 
 - Each sample uses an architecture infrastructure. This keeps the samples free of almost all setup.
 - Each infrastructure and sample features a `create.ipynb` for creation (and running) of the sample setup and a `main.bicep` file for IaC configuration.
 - Each infrastructure contains a `clean-up.ipynb` file to tear down everything in the infrastructure and its resource group. This reduces your Azure cost.
 - Samples (and infrastructures) may contain additional files specific to their use cases.
 
-### Infrastructure Architectures
+### 🏛️ Infrastructure Architectures
 
 We provide several common architectural approaches to integrating APIM into your Azure ecosystem. While these are high-fidelity setups, they are not production-ready. Please refer to the [Azure API Management landing zone accelerator](https://learn.microsoft.com/azure/cloud-adoption-framework/scenarios/app-platform/api-management/landing-zone-accelerator) for up-to-date production setups.
 
@@ -95,15 +95,15 @@ We provide several common architectural approaches to integrating APIM into your
 
 ---
 
-## Development
+## 🛠️ Development
 
 As you work with this repo, you will likely want to make your own customizations. There's little you need to know to be successful.
 
 The repo uses the bicep linter and has rules defined in `bicepconfig.json`. See the [bicep linter documentation](https://learn.microsoft.com/azure/azure-resource-manager/bicep/bicep-config-linter) for details.
 
 **We welcome contributions!** Please consider forking the repo and creating issues and pull requests to share your samples. Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details. Thank you! 
 
-### Adding a Sample
+### ➕ Adding a Sample
 
 Adding a new sample is relatively straight-forward.
 
@@ -115,11 +115,11 @@ Adding a new sample is relatively straight-forward.
 1. Test the sample with all supported infrastructures.
 1. Create a pull request for merge.
 
-### Testing & Code Coverage
+### 🧪 Testing & Code Coverage
 
 Python modules in `shared/python` are covered by comprehensive unit tests located in `tests/python`. All tests use [pytest](https://docs.pytest.org/) and leverage modern pytest features, including custom markers for unit and HTTP tests.
 
-#### Running Tests Locally
+#### 🚀 Running Tests Locally
 
 - **PowerShell (Windows):**
   - Run all tests with coverage: `./tests/python/run_tests.ps1`
@@ -136,26 +136,26 @@ You can also run tests manually and see details in the console:
 pytest -v --cov=shared/python --cov-report=html:tests/python/htmlcov --cov-report=term tests/python
 ```
 
-#### Viewing Coverage Reports
+#### 📊 Viewing Coverage Reports
 
 After running tests, open `tests/python/htmlcov/index.html` in your browser to view detailed coverage information.
 
-#### Pytest Markers
+#### 🏷️ Pytest Markers
 
 - `@pytest.mark.unit` — marks a unit test
 - `@pytest.mark.http` — marks a test involving HTTP/mocking
 
 Markers are registered in `pytest.ini` to avoid warnings.
 
-#### Continuous Integration (CI)
+#### ⚡ Continuous Integration (CI)
 
 On every push or pull request, GitHub Actions will:
 - Install dependencies
 - Run all Python tests in `tests/python` with coverage
 - Store the `.coverage` file in `tests/python`
 - Upload the HTML coverage report as a workflow artifact for download
 
-#### Additional Notes
+#### 📝 Additional Notes
 
 - The `.gitignore` is configured to exclude coverage output and artifacts.
 - All test and coverage features work both locally and in CI.
@@ -164,13 +164,13 @@ For more details on pytest usage, see the [pytest documentation](https://docs.py
 
 ---
 
-## Supporting Resources
+## 📚 Supporting Resources
 
 The APIM team maintains an [APIM policy snippets repo](https://github.com/Azure/api-management-policy-snippets) with use cases we have seen. They are not immediately executable samples and require integrations such as in this repo.
 
 ---
 
-## Acknowledgements
+## 🙏 Acknowledgements
 
 This project has its roots in work done by [Alex Vieira](https://github.com/vieiraae) on the excellent Azure API Management [AI Gateway](https://github.com/Azure-Samples/AI-Gateway) GitHub repository. Much of the structure is similar and its reuse resulted in significant time savings. Thank you, Alex!
 

assets/APIM-Samples-199x163.png

@@ -4,17 +4,17 @@ Secure architecture that takes all traffic off the public Internet once Azure Fr
 
 <img src="./Azure Front Door, API Management & Container Apps Architecture.svg" alt="Diagram showing Azure Front Door, API Management, and Container Apps architecture. Azure Front Door routes traffic to API Management, which then routes to Container Apps. Telemetry is sent to Azure Monitor." title="Azure Front Door, API Management & Container Apps Architecture" width="1000" />
 
-## Objectives
+## 🎯 Objectives
 
 1. Provide a secure pathway to API Management via a private link from Front Door
 1. Maintain private networking by integrating API Management with a VNet to communicate with Azure Container Apps. (This can also be achieved via a private link there)
 1. Empower users to use Azure Container Apps, if desired
 1. Enable observability by sending telemetry to Azure Monitor
 
-## Configuration
+## ⚙️ Configuration
 
 Adjust the `user-defined parameters` in this lab's Jupyter Notebook's [Initialize notebook variables](./create.ipynb#initialize-notebook-variables) section.
 
-## Execution
+## ▶️ Execution
 
 1. Execute this lab's [Jupyter Notebook](./create.ipynb) step-by-step or via _Run All_.

assets/APIM-Samples.pdn

@@ -15,7 +15,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Initialize notebook variables\n",
+    "### 🛠️ 1. Initialize notebook variables\n",
     "\n",
     "Configures everything that's needed for deployment. \n",
     "\n",
@@ -83,7 +83,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Create deployment using Bicep\n",
+    "### 🚀 2. Create deployment using Bicep\n",
     "\n",
     "Creates the bicep deployment into the previously-specified resource group. A bicep parameters file will be created prior to execution."
    ]
@@ -124,7 +124,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Approve Front Door private link connection to APIM\n",
+    "### 🔗 3. Approve Front Door private link connection to APIM\n",
     "\n",
     "In the deployed Bicep template, Azure Front Door will establish a private link connection to the API Management service. This connection should be approved. Run the following command to approve the connection."
    ]
@@ -170,7 +170,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Verify API Request Success via API Management\n",
+    "### ✅ 4. Verify API Request Success via API Management\n",
     "\n",
     "As we have not yet disabled public access to APIM, this request should succeed with a **200**."
    ]
@@ -196,7 +196,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Disabling API Management public network access\n",
+    "### 🔒 5. Disabling API Management public network access\n",
     "\n",
     "The initial `APIM` service deployment above cannot disable public network access. It must be disabled subsequently below."
    ]
@@ -231,7 +231,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Verify API Request Success via Azure Front Door & Failure with API Management\n",
+    "### ✅ 6. Verify API Request Success via Azure Front Door & Failure with API Management\n",
     "\n",
     "At this time only requests through Front Door should be successful and return a **200**. Requests to APIM that worked previously should result in a **403**."
    ]
@@ -269,8 +269,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "<a id='clean'></a>\n",
-    "### Clean up resources\n",
+    "### 🗑️ Clean up resources\n",
     "\n",
     "When you're finished experimenting, it's advisable to remove all associated resources from Azure to avoid unnecessary cost.\n",
     "Use the [clean-up notebook](clean-up.ipynb) for that."

assets/APIM-Samples.png

@@ -4,16 +4,16 @@ This architecture secures API traffic by routing requests through Azure API Mana
 
 <img src="./API Management & Container Apps Architecture.svg" alt="Diagram showing Azure API Management and Container Apps architecture. API Management routes traffic to Container Apps. Telemetry is sent to Azure Monitor." title="API Management & Container Apps Architecture" width="800" />
 
-## Objectives
+## 🎯 Objectives
 
 1. Provide a secure API gateway using Azure API Management
 1. Integrate API Management with Azure Container Apps for backend services
 1. Enable observability by sending telemetry to Azure Monitor
 
-## Configuration
+## ⚙️ Configuration
 
 Adjust the `user-defined parameters` in this lab's Jupyter Notebook's [Initialize notebook variables](./create.ipynb#initialize-notebook-variables) section.
 
-## Execution
+## ▶️ Execution
 
 1. Execute this lab's [Jupyter Notebook](./create.ipynb) step-by-step or via _Run All_.

infrastructure/afd-apim/README.md

@@ -17,7 +17,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Initialize notebook variables\n",
+    "### 🛠️ 1. Initialize notebook variables\n",
     "\n",
     "Configures everything that's needed for deployment. \n",
     "\n",
@@ -76,7 +76,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Create deployment using Bicep\n",
+    "### 🚀 2. Create deployment using Bicep\n",
     "\n",
     "Creates the bicep deployment into the previously-specified resource group. A bicep parameters file will be created prior to execution."
    ]
@@ -114,7 +114,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Verify API Request Success\n",
+    "### ✅ 3. Verify API Request Success\n",
     "\n",
     "Assert that the deployment was successful by making simple calls to APIM. "
    ]
@@ -141,8 +141,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "<a id='clean'></a>\n",
-    "### Clean up resources\n",
+    "### 🗑️ Clean up resources\n",
     "\n",
     "When you're finished experimenting, it's advisable to remove all associated resources from Azure to avoid unnecessary cost.\n",
     "Use the [clean-up notebook](clean-up.ipynb) for that."

infrastructure/afd-apim/create.ipynb

@@ -4,15 +4,15 @@ This architecture provides a basic API gateway using Azure API Management, suita
 
 <img src="./Simple API Management Architecture.svg" alt="Diagram showing a simple Azure API Management architecture. API Management acts as a gateway for API consumers. Telemetry is sent to Azure Monitor." title="Simple API Management Architecture" width="800" />
 
-## Objectives
+## 🎯 Objectives
 
 1. Provide the simplest Azure API Management infrastructure with a public ingress to allow for easy testing
 1. Enable observability by sending telemetry to Azure Monitor
 
-## Configuration
+## ⚙️ Configuration
 
 Adjust the `user-defined parameters` in this lab's Jupyter Notebook's [Initialize notebook variables](./create.ipynb#initialize-notebook-variables) section.
 
-## Execution
+## ▶️ Execution
 
 1. Execute this lab's [Jupyter Notebook](./create.ipynb) step-by-step or via _Run All_.

infrastructure/apim-aca/README.md

@@ -15,7 +15,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Initialize notebook variables\n",
+    "### 🛠️ 1. Initialize notebook variables\n",
     "\n",
     "Configures everything that's needed for deployment. \n",
     "\n",
@@ -59,7 +59,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Create deployment using Bicep\n",
+    "### 🚀 2. Create deployment using Bicep\n",
     "\n",
     "Creates the bicep deployment into the previously-specified resource group. A bicep parameters file will be created prior to execution."
    ]
@@ -95,7 +95,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Verify API Request Success\n",
+    "### ✅ 3. Verify API Request Success\n",
     "\n",
     "Assert that the deployment was successful by making simple calls to APIM. "
    ]
@@ -119,8 +119,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "<a id='clean'></a>\n",
-    "### Clean up resources\n",
+    "### 🗑️ Clean up resources\n",
     "\n",
     "When you're finished experimenting, it's advisable to remove all associated resources from Azure to avoid unnecessary cost.\n",
     "Use the [clean-up notebook](clean-up.ipynb) for that."